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INSTRUMENTS Entering the Profiling Environment 
TMS320C5x C Source Debugger The profiling evironment is supported under all platforms except 
: DOS. 
Profiler Reference Card 
Emulator: emudx -profile 
. = EVM: evm5x -profile 
Basic Profiling Commands Simulator:  sim5x —profile 


Debugger Commands That Can Be Used in the 
Profiling Environment 


Running a Profiling Session 2 MA PROMPT SR 
Command Description ALIAS MAP QUIT SYSTEM 
pf starting point |, update rate] Runa full profiling CD MC RELOAD TAKE 

session 
: P : , CLS MD RESET UNALIAS 
pq starting point [, update rate] Runa quick profil- 
ing session DASM MI RESTART USE 
pr [clear data [, update rate]] Resume a profilng DIR ML SA VAA 
session that has 
halted DLOG MOVE SCONFIG VAC 
ECHO MR SD VERSION 
EVAL MS SIZE VR 

Defining Stopping Points FILE PF SL WIN 
Command Description FUNC PQ SLOAD ZOOM 
sa address Add a stopping LOAD PR 

point 
: Debugger Commands That Can’t Be Used in the 
sd address Delete a stopping Profiling Environment 
point 
| CSTEP PESC SEND 
sr Delete all the stop- 
ping points @ DISP PHALT SET 
sl View a list of all ADDR FILL PING SETF 
current stopping 
points ASM GO PIND SOUND 
BA HALT PINL SPAWN 
BD HELP PRUN SSAVE 
BL HISTORY PRUNF STAT 

Saving Profile Data to a File BORDER MC PSTEP STEP 
Command Description BR MEM RETURN UNSET 
vac filename Save the contents Cc MIX RUN WA 

of the PROFILE 
window to a sys- CALLS NEXT RUNB WD 
tem file 
CNEXT PATCH RUNF WHATIS 
vaa filename Save all data for 


the current view COLOR PAUSE SCOLOR WR 


Marking Areas 


To mark this area 

Lines 

D By line number, address 
D All lines in a function 


Ranges 
D By line numbers 


Functions 

Oi By function name 

Q All functions in a module 
Q All functions everywhere 


Disabling Marked Areas 


To disable this area 
Lines 

Q By line number, address 
Q All lines in a function 

Q All lines in a module 

Q All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

D All ranges in a module 

D All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everywhere 


All areas 

D All areas in a function 
Q All areas in a module 
Q All areas everywhere 


C only 


MCLE filename, line number 


MCLF function 


MCRE filename, line number, line number 


MCFE function 
MCFM filename 
MCFG 


C only 


DCLE filename, line number 
DCLF function 

DCLM filename 

DCLG 


DCRE filename, line number 
DCRF function 

DCRM filename 

DCRG 


DCFE function 
DCFM filename 
DCFG 


DCAF function 
DCAM filename 
DCAG 


Disassembly only 


DALE address 

DALF function 

DALM filename 
DALG 


DARE address 

DARF function 

DARM filename 
DARG 


not applicable 


DAAF function 
DAAM filename 
DAAG 


Disassembly only 


MALE address 
MALF function 


MARE address, address 


not applicable 


not applicable 
DBLF function 
DBLM filename 
DBLG 


not applicable 
DBRF function 
DBRM filename 
DBRG 


not applicable 
DBFM filename 
DBFG 


DBAF function 
DBAM filename 
DBAG 


C and Disassembly 


Enabling Disabled Areas 


To disable this area 
Lines 

@ By line number, address 
Q All lines in a function 

D All lines in a module 

Q All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

D All ranges in a module 

QD All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everywhere 


All areas 

D All areas in a function 
Q All areas in a module 
Q All areas everywhere 


Unmarking Areas 


To disable this area 
Lines 

@ By line number, address 
Q All lines in a function 

D All lines in a module 

D All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

Q All ranges in a module 

Q All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everywhere 


All areas 

D All areas in a function 
Q All areas in a module 
Q All areas everywhere 


C only 


ECLE filename, line number 
ECLF function 

ECLM filename 

ECLG 


ECRE filename, line number 
ECRF function 

ECRM filename 

ECRG 


ECFE function 
ECFM filename 
ECFG 


ECAF function 
ECAM filename 
ECAG 


C only 


UCLE filename, line number 
UCLF function 

UCLM filename 

UCLG 


UCRE filename, line number 
UCRF function 

UCRM filename 

UCRG 


UCFE function 
UCFM filename 
UCFG 


UCAF function 
UCAM filename 
UCAG 


Disassembly only 


EALE address 

EALF function 

EALM filename 
EALG 


EARE address 

EARF function 

EARM filename 
EARG 


not applicable 


EAAF function 
EAAM filename 
EAAG 


Disassembly only 


UALE address 

UALF function 

UALM filename 
UALG 


UARE address 

UARF function 

UARM filename 
UARG 


not applicable 


UAAF function 
UAAM filename 
UAAG 


C and Disassembly 


not applicable 
EBLF function 
EBLM filename 
EBLG 


not applicable 
EBRF function 
EBRM filename 
EBRG 


not applicable 
EBFM filename 
EBFG 


EBAF function 
EBAM filename 
EBAG 


C and Disassembly 


not applicable 
UBLF function 
UBLM filename 
UBLG 


not applicable 
UBRF function 
UBRM filename 
UBRG 


not applicable 
UBFM filename 
UBFG 


UBAF function 
UBAM filename 
UBAG 


Changing the PROFILE Window Display 


Viewing specific areas 


To disable this area 
Lines 

Q By line number, address 
Q All lines in a function 

D All lines in a module 

Q All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

Q All ranges in a module 

D All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everywhere 


All areas 

Q All areas in a function 
Q All areas in a module 
Q All areas everywhere 


C only 


VFCLE filename, line number 
VFCLF function 

VFCLM filename 

VFCLG 


VFCRE filename, line number 
VFCRF function 

VFCRM filename 

VFCRG 


VFCFE function 
VFCFM filename 
VFCFG 


VFCAF function 
VFCAM filename 


Disassembly only 


VFALE address 

VFALF function 

VFALM filename 
VFALG 


VFARE address 

VFARF function 

VFARM filename 
VFARG 


not applicable 


VEFAAF function 
VFAAM filename 
VFAAG 


Sorting the data 


VFCAG 
Viewing different data 
To view this information Use this 

command 

Count VDC 
Inclusive VDI 
Inclusive, maximum VDN 
Exclusive VDE 
Exclusive, maximum VDX 
Address VDA 
All VDL 


To sort on this data 


Count 

Inclusive 

Inclusive, maximum 
Exclusive 

Exclusive, maximum 
Address 

Data 


C and Disassembly 


not applicable 
VFBLF function 
VFBLM filename 
VFBLG 


not applicable 
VFBRF function 
VFBRM filename 
VFBRG 


not applicable 
VFBFM filename 
VFBFG 


VFBAF function 
VFBAM filename 
VFBAG 


Use this 
command 


VSC 
VSI 

VSN 
VSE 
VSX 
VSA 
VSD 


TEXAS 4 
INSTRUMENTS 


TMS320C5x C Source Debugger 
Reference Card 


Phone Number 
DSP Hotline: (713) 274-2320 


Invoking the Debugger 

Emulator: emu5x [filename] [-options] 
EVM: evm5x [filename] [-options] 
Simulator: sim5x [filename] [-options] 
Debugger Options 

Option Description 

—b[b] Select the screen size. 


Option Chars. 
none 80 X 25 (default) 


—b 80 x 43 (EGA or VGA) 

—bb 80 x 50 (VGA only) 
-i pathname Identify additional directories. Identifies 

directories that contain source files. 
—mv50 Select the device version. (simulator 
—mv51 only) Identifies C50, 'C51, or’C53 memory 
—mv53 map (C50 is the default). 


-p portaddress Identify the port address. (emulator, 
SWDS, and EVM) Identifies the I/O port ad- 
dress that the debugger uses for communi- 
cating with the device. 


—profile Enter the profiling environment. (emula- 
tor and simulator) Brings up the debugger 
in a profiling environment. 


-Ss Load the symbol table only. Tells the 
debugger to load filename’s symbol table 
only. 

—t filename Identify a new initialization file. Allows 
you to specify an initialization file. 

Vv Load without the symbol table. Loads 


only global symbols; later, local symbols 
are loaded as needed. Affects all loads. 


—x Ignore D_OPTIONS. Ignores options 
supplied with D_OPTIONS. 


Summary of Debugger Commands 


? expression [, display format| 


addr address[@prog | @data] 
addr function name 


alias [alias name [, command string”) ] 
asm 

ba address 

bd address 

bl 

border [active] [, [ inactive] [,resize] ] 
br 

c 

calls 


cd [directory name] 
chdir [directory name] 


cls 

cnext [expression] 

color area, attr, [,attro [,attr3 [,attrg] ]] 
cstep [expression] 


dasm address[@prog | @data] 
dasm function name 


dir [directory] 

disp expression [, display format| 
dlog filename|[,{a | w}] 

echo string 


eval expression[@prog | @data] 
e expression[@prog | @data] 


file filename 
fill address, page, length, data 


func function name 
func address 


go [address] 
halt 


if Boolean expression 
debugger command list 
[else 

debugger command list] 
endif 


load object filename 


loop expression 
debugger command list 
endloop 


ma adoaress, page, length, type 


map {on | off} 


p = profiler only d = basic debugger only 
b = both profiler and basic debugger simulator only 


Q 


cereeaqaeakgrRreReaeRkeeeeese 


cs, oT oc Qa ft Sereaaqeags 


qo 


Summary of Debugger Commands 
mc port address, page, filename, {READ | WRITE} 
md address, page 
mem|#] expression [, display format| 
mi port address, page, {READ|WRITE} 

mix 

ml 

move [X, Y[, width, length ] ] 

mr 

ms address, page, length, filename 

next [expression] 

patch address, assembly language instruction 


pf starting point |, update rate] 
pine pinname filename 


pind pinname 

pinl 

pq starting point, update rate] 
pr [clear data [, update rate] | 
prompt new prompt 

quit 

reload object filename 

reset 


restart 
rest 


return 
ret 


run [expression] 

runb 

runf 

sa address 

scolor area, attr; [, attro [, attr3 [, attrg]]] 
sconfig [filename] 

sd address 

setf [data type, display format ] 
size [width, length | 

sl 

sload object filename 

sound on | off 

sr 

ssave [filename] 

step [expression] 


p = profiler only d = basic debugger only 
b = both profiler and basic debugger simulator only 


Q 


aeaetrvanatdsvd TSF AQtspwpeaesdrceerkReie 


Summary of Debugger Commands 


system [DOS command [, flag ] b 
take batch filename [, suppress echo flag] b 
unalias alias name b 
unalias * 
use directory name b 
vaa filename p 
vac filename p 
version b 
vr p 
wa expression [,[ label], display format | d 
wd index number d 
whatis symbol! d 
win WINDOW NAME b 
wr d 
zoom b 
p= profiler only d = basic debugger only 
b = both profiler and basic debugger T simulator only 

Border Styles 

(BORDER Command) 
Index Style 
0 Double-lined box 
1 Single-lined box 
2 Solid 1/2-tone top, double-lined sides/bottom 
3 Solid 1/4-tone top, double-lined sides/bottom 
4 Solid box, thin border 
5 Solid box, heavy sides, thin top/bottom 
6 Solid box, heavy borders 
7 Solid 1/2-tone box 
8 Solid 1/4-tone box 

Colors and Attributes 

(COLOR/SCOLOR Commands) 
black blue green cyan 
red magenta yellow white 
bright blink 

Area Names 

(COLOR/SCOLOR Commands) 
menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd _win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt  cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


Memory Types 


To identify this kind of Use this keyword as the 
memory type parameter 
read-only memory R, ROM, or READONLY 
write-only memory W, WOM, or WRITEONLY 
read/write memory R|W or RAM 
no-access memory PROTECT 
input port IPORT or IN PORT 
output port OPORT or OUT PORT 
input/output port IOPORT 
Display Formats 


(?, DISP, MEM, SETF, and WA Commands) 


Para- Result 
meter 


Para- Result 
meter 


. Default for the data type oO Octal 


c ASCII character (bytes) p Valid address 


d Decimal s  ASCllstring T 


e Exponential floating u Unsigned decimal 


point 


f Decimal floating point xX Hexadecimal 


t+ ?, DISP, SETF, and WA commands only 


Switching Modes 
Use this 
To do this function key 
Switch debugging modes in this order: 
o auto ——» assembly — 
Running Code 
Use these 
To do this function keys 
Run code from the current PC 
Single-step from the current PC 


Single-step code from the current PC; step 
over function calls 


Selecting or Closing a Window 


Use these 
To do this function keys 
Select the active window 
Close the CALLS or DISP window 


Editing Text on the Command Line 


Use these 
To do this function keys 
Enter the current command 
Move back over text without erasing char- 
acters or 


Move forward through text without erasing CTRL 
characters 


Move back over text while erasing charac- DELETE 
ters 


characters 


Move forward through text while erasing 


Insert text into the characters that are al- INSERT 
ready on the command line 


Using the Command History 


Use these 
To do this function keys 
Repeat the last command that you entered 


Move backward, one command at a time, TAB 
through the command history 


Move forward, one command at a time, 


through the command history 


Editing Data or Selecting the Active Field 


Use this 
To do this function key 


1} FILE or DISASSEMBLY window: Set 
or clear a breakpoint 


L} CALLS window: Display the source to 
a listed function 


L) Any data-display window: Edit the con- 
tents of the current field 


O DISP window: Open an additional 
DISP window 


Halting or Escaping From an Action 


Use this 
To do this function key 
O Halt program execution ESC 


QO Close a pulldown menu 


L} Undo an edit of the active field in a 
data-display window 


L} Halt the display of a long list of data 


Displaying Pulldown Menus 


Use these 
To do this function keys 
Display the Load menu ALT 


Display the Break menu 


b> 
[F) 


Display the Watch menu 


> 
4 


Display the Memory menu (mJ 
Display the Color menu ALT 
Display the MoDe menu (0) 
Display the Pin menu at] (P] 
Display the Analysis menu ALT (A) 
Display an adjacent menu or 
Execute any of the choices from a Press the high- 
displayed pulldown menu lighted letter 


corresponding 
to your choice 
Moving or Sizing a Window 


Enter the MOVE or SIZE command without parameters, then use 
the arrow keys: 


Use these 
To do this function keys 
QO Move the window down one line (¥) 
(1) Make the window one line longer 
CL} Move the window up one line (4) 
L) Make the window one line shorter 
CL) Move the window left one character 
position 
L) Make the window one character nar- 
rower 
C1 Move the window right one character 
position 
O Make the window one character 


wider 


Scrolling the Active Window’s Contents 


To do this 


Scroll up through the window contents, one 
window length at a time 


Scroll down through the window contents, 
one window length at a time 


Move the field cursor up one line at a time 
Move the field cursor down one line atatime 


[1 FILE window only: Scroll left 8 char- 
acters at a time 


1) Other windows: Move the field cur- 
sor left 1 field; at the first field on a 
line, wrap back to the last fully dis- 
played field on the previous line 


L) FlLEwindowonly:Scroll right 8 char- 
acters at a time 


C) Other windows: Move the field cur- 
sor right 1 field; at the last field ona 
line, wrap around to the first field on 
the next line 


FILE window only: Adjust the window’s con- 
tents so that the first line of the text file is at 
the top of the window 


FILE window only: Adjust the window’s con- 
tents so that the last line of the text file is at 
the bottom of the window 


DISP windows only: Scroll up through an 
array of structures 


DISP windows only: Scroll down through an 
array of structures 


Use these 
function keys 


4) 
Wy) 
Cal 


[4 


CTRL 


lohy) 
o> 

Q) 
eI 


CTRL 


PAGE 
UP 
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Tl warrants performance of its semiconductor products and related software to the specifications 
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Inclusion of TI products in such applications is understood to be fully at the risk of the customer. 
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In order to minimize risks associated with the customer’s applications, adequate design and 
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WARNING 


This equipment is intended for use in a laboratory test environment only. It generates, uses, and 
can radiate radio frequency energy and has not been tested for compliance with the limits of com- 
puting devices pursuant to subpart J of part 15 of FCC rules, which are designed to provide rea- 
sonable protection against radio frequency interference. Operation of this equipmentin other en- 
vironments may cause interference with radio communications, in which case the user at his own 
expense will be required to take whatever measures may be required to correct this interference. 


Preface 


Read This First 


What Is This Book About? 


This book tells you how to use the TMS320C5x C source debugger with these 
debugging tools: 


[J Emulator 
[J Evaluation module (EVM) 
[__] Simulator 


Each tool has its own version of the debugger. These versions operate almost 
identically; however, the executable files that invoke them are very different. 
For example, the EVM version won’t work with the emulator or simulator, and 
vice versa. Separate commands are provided for invoking each version of the 
debugger. 


There are two debugger environments: the basic debugger environment and 
the profiling environment. The basic debugger environment is a 
general-purpose debugging environment. The profiling environment is a 
special environment for collecting statistics about code execution. Both 
environments have the same easy-to-use interface. 


In addition to the debugger environments, you can use the parallel debug 
manager (PDM) with the emulator version of the debugger. The PDM allows 
you to control and coordinate multiple debuggers, giving you the flexibility and 
power to debug your entire application for your multiprocessing system. The 
PDM and its functions and features are described in this book. 


Before you use this book, you should use the appropriate installation guide to 
install the C source debugger and any necessary hardware. 


Read This First V 


How to Use This Manual 


How to Use This Manual 


vi 


The goal of this book is to help you learn to use the Texas Instruments standard 
programmer's interface for debugging. This book is divided into three distinct 
parts: 


(_} Part I: Hands-On Information is presented first so that you can start 
using your debugger the same day you receive it. 


HM Chapter 1 lists the key features of the debugger, describes additional 
’C5x software tools, tells you how to prepare a ’C5x program for 
debugging, and provides instructions and options for invoking the 
debugger and the PDM. 


M@ Chapter 2 describes the PDM and the commands that you can use to 
control multiple debuggers. 


MH Chapter 3 is a tutorial that introduces you to many of the debugger 
features. 


(_} Part ll: Debugger Description contains detailed information about using 
the debugger. 


The chapters in Part II detail the individual topics that are introduced in the 
tutorial. For example, Chapter 4 describes all of the debugger’s windows 
and tells you how to move them and size them; Chapter 5 describes 
everything you need to know about entering commands. 


(_] Part Ill: Reference Material provides supplementary information. 


HM Chapter 13 gives a complete reference to all the tasks introduced in 
Parts | and Il. This includes a functional and an alphabetical reference 
of the debugger commands and a topical reference of function key 
actions. 


HM Chapter 14 provides information about C expressions. The debugger 
commands are powerful because they accept C expressions as 
parameters; however, the debugger can also be used to debug 
assembly language programs. The information about C expressions 
will aid assembly language programmers who are unfamiliar with C. 


@ Part Ill also includes a glossary and an index. 


The way you use this book should depend on your experience with similar 
products. As with any book, it would be best for you to begin on page 1 and 
read to the end. Because most people don’t read technical manuals from cover 
to cover, here are some suggestions about what you should read. 


How to Use This Manual / Notational Conventions 


_] Ifyou have used TI development tools or other debuggers before, then you 
may want to: 


@ Read the introductory material in Chapter 1. 


If you plan to debug an application for a multiprocessing system, read 
Chapter 2. 


HM Complete the tutorial in Chapter 3. 


M@ Read the alphabetical command reference in Chapter 13. 


(_] If this is the first time that you have used a debugger or similar tool, then 
you may want to: 


M@ Read the introductory material in Chapter 1. 


HM lif you plan to debug an application for a multiprocessing system, read 
Chapter 2. 


M@ Complete the tutorial in Chapter 3. 
@ Read all of the chapters in Part Il. 


Notational Conventions 
This document uses the following conventions. 


_J The TMS320C50, TMS320C51, TMS320C52, and TMS320C53 
processors are referred to collectively as the ’C5x. 


[_] The C source debugger has a very flexible command-entry system; there 
are usually a variety of ways to perform any specific action. For example, 
you may be able to perform the same action by typing ina command, using 
the mouse, or using function keys. This document uses three symbols to 
identify the methods that you can use to perform an action: 


Symbol Description 


Identifies an action that you perform by using the mouse. 


Identifies an action that you perform by using function keys. 


: Identifies an action that you perform by typing in a 
command. 
<a 
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Notational Conventions 


(_] The following symbols identify mouse actions. For simplicity, these 
symbols represent a mouse with two buttons. However, you can use a 
mouse with only one button or a mouse with more than two buttons. 


Symbol Action 


as Point. Without pressing a mouse button, move the mouse to 
point the cursor at a window or field on the display. (Note that 
the mouse cursor displayed on the screen is not shaped like an 
arrow; it’s shaped like a block.) 


it Press and hold. Press a mouse button. If your mouse has only 
one button, press it. If your mouse has more than one button, 
press the left button. 


U0 Release. Release the mouse button that you pressed. 


Il Click. Press a mouse button and, without moving the mouse, 
release the button. 


A) Drag. While pressing the left mouse button, move the mouse. 


[_} Debugger commands are not case sensitive; you can enter them in 
lowercase, uppercase, or a combination. To emphasize this fact, 
commands are shown throughout this user’s guide in both uppercase and 
lowercase. 


(_] Program listings and examples, interactive displays, and window contents 
are shown in a special font. Some examples use a bold version to identify 
code, commands, or portions of an example that you enter. Here is an 


example: 
Command Result displayed in the COMMAND window 
whatis giant struct zzz giant[100]; 
whatis xxx struct xx { 
int a; 
int b; 
int c¢; 
int £1 © 2; 
int £2 3 4; 


Struct xxx *£3% 
int £4[10]; 


In this example, the left column identifies debugger commands that you 
type in. The right column identifies the result that the debugger displays in 
the COMMAND window display area. 


viii 


Notational Conventions / Information About Cautions 


(_] In syntax descriptions, the instruction or commandis in a bold face font, 
and parameters are in italics. Portions of a syntax that are in bold face 
should be entered as shown; portions of a syntax that are in italics 
describe the kind of information that should be entered. Here is an 
example of a command syntax: 


mem_ expression |, display format | 


mem is the command. This command has two parameters, indicated by 
expression and display format. The first parameter must be an actual C 
expression; the second parameter, which identifies a specific display 
format, is optional. 


(_} Square brackets ([ and ] ) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets; you 
don’t enter the brackets themselves. Here’s an example of a command 
that has an optional parameter: 


run [expression] 


The RUN command has one parameter, expression, which is optional. 


_j Braces( {and} ) indicate alist. The symbol | (read as or) separates items 
within the list. Here’s an example of a list: 


sound {on | off} 
This provides two choices: sound on or sound off. 


Unless the list is enclosed in square brackets, you must choose one item 
from the list. 


Information About Cautions 


This is an example of a caution statement. 


A caution statement describes a situation that could potentially 


damage your software or equipment. 


Please read each caution statement carefully. 
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Related Documentation From Texas Instruments 


The following books describe the TMS320C5x DSPs and related support 
tools. To obtain a copy of any of these TI documents, call the Texas 
Instruments Literature Response Center at (800) 477-8924. When ordering, 
please identify the book by its title and literature number. 


TMS320 Fixed-Point DSP Assembly Language Tools User’s Guide 
(literature number SPRUO18) describes the assembly language tools 
(assembler, linker, and other tools used to develop assembly language 
code), assembler directives, macros, common object file format, and 
symbolic debugging directives for the ’C1x, ‘C2x, and ’C5x generations 
of devices. 


TMS320C2x/C5x Optimizing C Compiler User’s Guide (literature number 
SPRU024) describes the ’C2x/C5x C compiler. This C compiler accepts 
ANSI standard C source code and produces TMS320 assembly 
language source code for the ’C2x and ’C5x generations of devices. 


TMS320C5x User’s Guide (literature number SPRUO56) describes the 
TMS320C5x 16-bit, fixed-point, general-purpose digital signal 
processors. Covered are its architecture, internal register structure, 
instruction set, pipeline, specifications, DMA, and I/O ports. Software 
applications are covered in a dedicated chapter. 


If you are an assembly language programmer and would like more information 
about C or C expressions, you may find this book useful: 


The C Programming Language (second edition, 1988), by Brian W. 
Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood 
Cliffs, New Jersey. 


If You Need Assistance. . . 


Trademarks 
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Request more information about 
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Processing (DSP) products 


Order Texas Instruments 
documentation 


Ask questions about product 
operation or report suspected 
problems 


Report mistakes in this document 
or any other Tl documentation 


If You Need Assistance / Trademarks 


Do this. . . 
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Texas Instruments Incorporated 

Market Communications Manager, MS 736 
P.O. Box 1443 

Houston, Texas 77251-1443 


Call the TI Literature Response Center: 
(800) 477-8924 


Call the DSP hotline: 
(713) 274-2320 
FAX: (713) 274-2324 


Fill out and return the reader response card at 
the end of this book, or send your comments to: 
Texas Instruments Incorporated 

Technical Publications Manager, MS 702 

P.O. Box 1443 

Houston, Texas 77251-1443 


MS-DOS and MS-Windows are registered trademarks of Microsoft Corp. 


PC-DOS and OS/2 are trademarks of International Business Machines Corp. 


Sun-3, Sun-4, SunOS, and OpenWindows are trademarks of Sun 


Microsystems, Inc. 


VAX and VMS are trademarks of Digital Equipment Corp. 


UNIX is a registered trademark of Unix System Laboratories, Inc. 


X Window System is a trademark of the Massachusetts Institute of 


Technology. 
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Chapter 1 


Overview of a Code 
Development and Debugging System 


The TMS320C5x C source debugger is an advanced programmer’s interface 
that helps you to develop, test, and refine ’C5x C programs (compiled with the 
’C5x optimizing ANSI C compiler) and assembly language programs. The 
debugger is the interface to the >C5x EVM, simulator, and unique scan-based, 
realtime emulator. 


This chapter gives an overview of the programmer’s interface, describes the 
’°C5x code development environment, and provides instructions and options 
for invoking the debugger. This chapter also describes the parallel debugger 
manager (PDM) for use with the ’C5x emulator. 
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Description of the ‘C5x C Source Debugger 


1.1. Description of the ’C5x C Source Debugger 


The ’C5x C source debugging interface improves productivity by allowing you 
to debug a program in the language it was written in. You can choose to debug 
your programs in C, assembly language, or both. And, unlike many other de- 
buggers, the ’C5x debugger’s higher level features are available even when 
you’re debugging assembly language code. 


The Texas Instruments advanced programmer’s interface is easy to learn and 
use. Its friendly window-, mouse-, and menu-oriented interface reduces learn- 
ing time and eliminates the need to memorize complex commands. The de- 
bugger’s customizable displays and flexible command entry let you develop 
a debugging environment that suits your needs—you won’t be locked into a 
rigid environment. A shortened learning curve and increased productivity re- 
duce the software development cycle, so you'll get to market faster. 


Figure 1-1 identifies several features of the debugger display. 


Figure 1-1. The Basic Debugger Display 
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Key features of the debugger 


_} Multilevel debugging. The debugger allows you to debug both C and 
assembly language code. If you’re debugging a C program, you can 
choose to view just the C source, the disassembly of the object code 
created from the C source, or both. You can also use the debugger as an 
assembly language debugger. 


(_} Fully configurable, state-of-the-art, window-oriented interface. The 
C source debugger separates code, data, and commands into manage- 
able portions. Use any of the default displays. Or, select the windows you 
want to display, size them, and move them where you want them. 


[_} Comprehensive data displays. You can easily create windows for 
displaying and editing the values of variables, arrays, structures, point- 
ers—any kind of data—in their natural format (float, int, char, enum, or 
pointer). You can even display entire linked lists. 


--WATCH 


--DISP: str | 
a 123 A stro 
b 0 D 2: FO 1.000000e 
c 75435/-DISP: *str.£3 —_ 3: color GREEN 
Aes a 8327 A 
£2, 6 b 666 ' 
£3 Ox00f| c 87213,;-DISP: *str.£3->£3 al 
seh [oe all|| sah 25 a us A 
£2, «27 b 3212 
£3 Ox00f; c 782 | 
£4 a faut“ 
: £2 9 v 
£3 0x00f£000a 
a £4 [...-] 


[_.] On-screen editing. Change any data value displayed in any window— 
just point the mouse, click, and type. 


[_] Continuous update. The debugger continuously updates information on 
the screen, highlighting changed values. 


(_} Powerful command set. Unlike many other debugging systems, this 
debugger doesn’t force you to learn a large, intricate command set. The 
’C5x C source debugger supports a small but powerful command set that 
makes full use of C expressions. One debugger command performs 
actions that would take several commands in another system. 
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Description of the ‘C5x C Source Debugger 


[_] Flexible command entry. There are a variety of ways to enter com- 


mands. You can type commands or use a mouse, function keys, or the 
pulldown menus; choose the method that you like best. Want to re-enter 
a command? No need to retype it—simply use the command history. 


Create your own debugger. The debugger display is completely confi- 
gurable, allowing you to create the interface that is best suited for your use. 


HM If you’re using a color display, you can change the colors of any area 
on the screen. 


M You can change the physical appearance of display features such as 
window borders. 


M You can interactively set the size and position of windows in the 
display. 


Create and save as many custom configurations as you like, or use the 
defaults. Use the debugger with a color display or a black-and-white 
display. A color display is preferable; the various types of information on 
the display are easier to distinguish when they are highlighted with color. 


Variety of screen sizes. The debugger’s default configuration is set up 
for atypical PC display, with 25 lines by 80 characters. If you use a sophis- 
ticated graphics card, you can take advantage of the debugger’s addition- 
al screen sizes. A larger screen size allows you to display more informa- 
tion and provides you with more screen space for organizing the display— 
bringing the benefits of workstation displays to your PC. 


All the standard features you expect in a world-class debugger. The 
debugger provides you with complete control over program execution with 
features like conditional execution and single-stepping (including 
single-stepping into or over function calls). You can set or clear a break- 
point with a click of the mouse or by typing commands. You can define a 
memory map that identifies the portions of target memory that the debug- 
ger can access. You can choose to load only the symbol table portion of 
an object file to work with systems that have code in ROM. The debugger 
can execute commands from a batch file, providing you with an easy 
method for entering often-used command sequences. 


Description of the Analysis Interface 


1.2 Description of the Analysis Interface 


In addition to the basic debugger features, the ’C5x has an analysis module 
on the chip that allows the emulator to monitor the operations of your target 
system. This expands your debugging capabilities beyond simple software 
breakpoints. 


The interface to the analysis module provides you with easy-to-use windows, 
dialog boxes, and commands that give you a detailed look into the operations 
of your target system. The analysis interface captures ’C5x bus cycle informa- 
tion in real time and reacts to this information through actions such as hard- 
ware breakpoints and event counting. Such features give you the ability to stop 
the processor and track the path your program took before reaching the break- 
point or event. 


Key features of the analysis interface 


(_] Event counting. You have the option of counting the number of times a 
defined event occurred during execution of your program or stopping after 
a certain number of events have been detected. You can count only one 
event at a time, including: 


@ Bus accesses @ Interrupts or traps taken 

@ CPU clock cycles @ Returns from interrupts, traps, or calls 
 Calls/branches taken @ Instruction fetches 

Pipeline clocks 


(_] Hardware breakpoints. You can also set up the analysis interface to halt 
the processor during execution of your program. The events that cause 
the processor to stop are called break events. A break event can define 
a variety of conditions, including: 


@ Bus accesses @ Interrupts or traps taken 

Hi Pipeline clock i Returns from interrupts, traps, or calls 
@ Calls/branches taken @ Event counter passing zero 

@ Discontinuity i Low levels on EMU0/1 pins 


(_} Set up EMUO/1 pins. In a system of multiple ’C5x processors connected 
by EMU0/1 (emulation event) pins, setting up the EMU0/1 pins allows you 
to create global breakpoints. Whenever one processor in your system 
reaches a breakpoint (software or hardware), a// processors in the system 
can be halted. 


[_} View the PC discontinuity stack. Discontinuity occurs when the ad- 
dresses fetched by the debugger become nonsequential as a result of 
loading the PC (through branches, calls, return instructions, for example) 
with new values. You can view these values through the PC discontinuity 
stack and easily track the progress of your program to see exactly how the 
debugger reached its current state. 
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1.3 Description of the Profiling Environment 


In addition to the basic debugging environment, a second environment—the 
profiling environment—is available. The profiling environment provides a 
method for collecting execution statistics about specific areas in your code. 
This gives you immediate feedback on your application’s performance. The 
profiler is not available when you’re running the debugger under DOS. 


Figure 1—2 identifies several features of the debugger display within the profil- 


ing environment. 


Figure 1-2. The Profiling-Environment Display 
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Key features of the profiling environment 


pulldown menu 
provides access 
to often-used 
basic debugger 
commands plus 
special profiling 
commands 


profiling areas 
are Clearly 
marked 


The profiling environment builds on the same easy-to-use interface available 
in the basic debugging environment and has these additional features: 


_]} More efficient code. Within the profiling environment, you can quickly 
identify busy sections in your programs. This helps you to direct valuable 
development time toward streamlining the sections of code that most dra- 
matically affect program performance. 
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[_] Statistics on multiple areas. You can collect statistics about individual 
statements in disassembly or C, about ranges in disassembly or C, and 
about C functions. When you are collecting statistics on many areas, you 
can choose to view the statistics for all the areas or a subset of the areas. 


[_} Comprehensive display of statistics. The profiler provides all the infor- 
mation you need for identifying bottlenecks in your code: 


mM The number of times each area was entered during the profiling 
session. 


H The total execution time of an area, including or excluding the execu- 
tion time of any subroutines called from within the area. 


M@ The maximum time for one iteration of an area, including or excluding 
the execution time of any subroutines called from within the area. 


Statistics may be updated continuously during the profiling session or at 
selected intervals. 


(_} Configurable display of statistics. Display the entire set of data, or 
display one type of data at a time. Display all the areas you’re profiling, or 
display a selected subset of the areas. 


(_} Visual representation of statistics. When you choose to display one 
type of data at a time, the statistics will be accompanied by histograms for 
each area, showing the relationship of each area’s statistics to those of the 
other profiled areas. 


_] Disabled areas. In addition to identifying areas that you can collect 
statistics on, you can also identify areas that you don’t want to affect the 
statistics. This removes the timing impact from code such as a standard 
library function or a fully optimized portion of code. 


(_] Special profiling commands. The profiling environment supports a rich 
set of commands to help you select areas and display information. Some 
of the basic debugger commands—such as the memory map 
commands—may be necessary during profiling and are available within 
the profiling environment. Other commands—such as_ breakpoint 
commands and run commands—are not necessary and are therefore not 
available within the profiling environment. 
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1.4 Description of the Parallel Debug Manager (PDM) 


The TMS320C5x emulation system is a true multiprocessing debugging sys- 
tem. It allows you to debug your entire application by using the parallel debug 
manager (PDM). The PDM is acommand shell that controls and coordinates 
multiple debuggers, providing you with the ability to: 


Create and control debuggers for one or more processors 
Organize debuggers into groups 
Send commands to one or more debuggers 


Synchronously run, step, and halt multiple processors in parallel 


UCU oOd wv 


Gather system information in a central location 


You can operate the PDM only on PCs running OS/2 or Sun workstations run- 
ning OpenWindows. The PDM is invoked and PDM commands are executed 
from a command shell window under the host windowing system. From the 
PDM, you can invoke and control debuggers for each of the processors in your 
multiprocessing system. 


As Figure 1-3 shows, you can run multiple debuggers under the control of the 
PDM. 


Figure 1-3. The PDM Environment 


CPU_A CPU_B CPU_C CPU_D CPU_E CPU_x 
debugger debugger debugger debugger debugger debugger 


1.5 Developing 


Developing Code for the ’'C5x 


Code for the ’C5x 


The ‘C5x is well supported by a complete set of hardware and software 
development tools, including a C compiler, assembler, and linker. Figure 1—4 
illustrates the ’C5x code development flow. The most common paths of soft- 
ware development are highlighted in grey; the other portions are optional. 


Figure 1-4. ’C5x Software Development Flow 
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Developing Code for the 'C5x 


These tools use common object file format (COFF), which encourages 
modular programming. COFF allows you to divide your code into logical 
blocks, define your system’s memory map, and then link code into specific 
memory areas. COFF also provides rich support for source-level debugging. 


The following list describes the tools shown in Figure 1-4. 


The ’C5x optimizing ANSI C compiler is a full-featured optimizing compiler 
that translates standard ANSI C programs into ’C5x assembly language 


source. Key characteristics include: 


(_] Standard ANSI C. The ANSI standard is a precise definition of the C 


language, agreed upon by the C community. The standard encompasses 
most of the recent extensions to C. To an increasing degree, ANSI confor- 
mance is a requirement for C compilers in the DSP community. 


Optimization. The compiler uses several advanced techniques for 
generating efficient, compact code from C source. 


Assembly language output. The compiler generates assembly lan- 
guage source that you can inspect (and modify, if desired). 


ANSI standard runtime support. The compiler package comes with a 
complete runtime library that conforms to the ANSI C library standard. The 
library includes functions for string manipulation, dynamic memory alloca- 
tion, data conversion, timekeeping, trigonometry, exponential operations, 
and hyperbolic operations. Functions for I/O and signal handling are not 
included, because they are application specific. 


Flexible assembly language interface. The compiler has straightfor- 
ward calling conventions, allowing you to easily write assembly and C 
functions that call each other. 


Shell program. The compiler package includes a shell program that 
enables you to compile, assemble, and link programs in a single step. 


Source interlist utility. The compiler package includes a utility that inter- 
lists your original C source statements into the assembly language output 
of the compiler. This utility provides you with an easy method for inspecting 
the assembly code generated for each C statement. 


assembler 


linker 


debugging 
tools 


hex 
conversion 
utility 


Developing Code for the ’C5x 


The assembler translates ’C5x assembly language source files into machine 
language object files. 


The linker combines object files into a single, executable object module. As 
the linker creates the executable module, it performs relocation and resolves 
external references. The linker is a tool that allows you to define your system’s 
memory map and to associate blocks of code with defined memory areas. 


The main purpose of the development process is to produce a module that can 
be executed in a ’C5x target system. You can use one of several debugging 
tools to refine and correct your code. Available products include: 


[_] A realtime in-circuit emulator, 


[_] An evaluation module (EVM), and 


_} A software simulator. 


Each of these tools uses the ’C5x debugger as a software interface. 


A hex conversion utility is also available; it converts a COFF object file into 
an ASCIl-Hex, Intel, Motorola-S, Tektronix, or Tl-tagged object-format file that 
can be downloaded to an EPROM programmer. 
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1.6 Preparing Your Program for Debugging 


Figure 1—5 illustrates the steps you must go through to prepare a program for 
debugging. 


Figure 1—5. Steps You Go Through to Prepare a Program 


If you’re working with a C | 
program, start here Cc 
source 
C Compiler 


If you're working with an : assembly 
assembly language : language 


program, start here * code 
Assembler 


sexecutable: 
‘object code’ 


This is the file that you load 
when you invoke the 
debugger 


If you’re preparing to 1) Compile the program; use the —g option. If you 
debug aC program. .. plan to use the profiler, compile the program with 
the —as option. 


2) Assemble the resulting assembly language pro- 
gram. 


3) Link the resulting object file. 


This produces an object file that you can load into the 


debugger. 
If you’re preparing to 1) Assemble the assembly language source file. 
debug an assembly 2) Link the resulting object file. 


language program... ; ; ; 
This produces an object file that you can load into the 


debugger. 


You can compile, assemble, and link a program by invoking the compiler, 
assembler, and linker in separate steps; or you can perform all three actions 
in a single step by using the DSPCL shell program. The TMS320 Fixed-Point 
DSP Assembly Language Tools User’s Guide and TMS320C2x/C5x Optimiz- 
ing C Compiler User’s Guide contain complete instructions for invoking the 
tools individually and for using the shell program. 


Preparing Your Program for Debugging 


For your convenience, here’s the command for invoking the shell program 
when preparing a program for debugging: 


dspcl [-options] -g [filenames] [-z [link options]] 


dspcl 


options 


filenames 


-9 


—Z 


link options 


is the command that invokes the compiler and assembler. 


affect the way the shell processes input files. If you plan to use 
the debugger’s profiling environment, include the —as option. 


are one or more C source files, assembly language source files, 
or object files. Filenames are not case sensitive. 


is an option that tells the C compiler to produce symbolic debug- 
ging information. When preparing a C program for debugging, 
you must use the —g option. 


is an option that invokes the linker. After compiling/assembling 
your programs, you can invoke the linker in a separate step. If 
you want the shell to automatically invoke the linker, however, 
use —Z. 


affect the way the linker processes input files; use these options 
only when you use —z. 


Options and filenames can be specified in any order on the command line, but 
if you use —z, it must follow all C/assembly language source filenames and 
compiler options. 


The shell identifies a file’s type by the filename’s extension. 


Extension File Type File Description 

Cc C source compiled, assembled, 
and linked 

.asm assembly language assembled and linked 

source 

.S* (any extension that assembly language assembled and linked 

begins with s) source 

.o* (extension begins object file linked 

with 0) 

none (.c assumed) C source compiled, assembled, 
and linked 
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1.7. Invoking the Debuggers and the PDM 


If you are using an emulator, there are two ways to invoke the debugger: 


[.} You can invoke astandalone debugger that is notcontrolled by the parallel 
debug manager (PDM), or 


[_] You can invoke several debuggers that are under control of the PDM. 


If you are using a simulator or EVM, you can invoke only a standalone de- 
bugger. 


This section describes how to invoke any version of the debugger and how to 
invoke the PDM. 


Invoking a standalone debugger 


===> 


Here’s the basic format for the command that invokes a standalone debugger: 


emulator: emu5x [filename] [—options] 
EVM: evm5dx [filename] [—options] 
simulator: sim5x_ [filename] [—options] 


__] emu5x, evm5x, and sim5x are the commands that invoke the debugger. 
Enter one of these commands from the operating-system command line. 


_] filenameis an optional parameter that names an object file that the debug- 
ger loads into memory during invocation. The debugger looks for the file 
in the current directory; if the file isn’t in the current directory, you must sup- 
ply the entire pathname. If you don’t supply an extension for the filename, 
the debugger assumes that the extension is .out, unless you're using mul- 
tiple extensions; you must specify the entire filename if the filename has 
more than one extension. 


[_] -options supply the debugger with additional information. See Section 
1.8, page 1-17, for a complete list of debugger options. 


Invoking the Debuggers and the PDM 


Invoking multiple debuggers (emulator only) 


Before you can invoke multiple debuggers in a multiprocessing environment, 
you must first invoke the parallel debug manager (PDM). The PDM is invoked 
and PDM commands are executed from a command shell window under the 
host windowing system. The format for invoking the PDM is: 


pdm _[-t filename] 


Once the PDM is invoked, you will see the PDM command prompt (PDM:1>>) 
and can begin entering commands. 


When you invoke the PDM, it looks for a file called init.pdm. This file contains 
initialization commands for the PDM. The PDM searches for the init.pdm file 
in the current directory and in the directories you specify with the D_DIR envi- 
ronment variable. If the PDM can’t find the initialization file, you will see this 
message: Cannot open take file. 


a | 


Note: 


The PDM environment uses the interprocess communication (IPC) features 
of UNIX (shared memory, message queues, and semaphores) to provide 
and manage communications between the different tasks. If you are not sure 
whether the IPC features are enabled, see your system administrator. To use 
the PDM environment, you should be familiar with the IPC status (ipcs) and 
IPC remove (ipcrm) UNIX commands. If you use the UNIX task kill (kill) com- 
mand to terminate execution of tasks, you will also need to use the ipcrm 
command to terminate the shared memory, message queues, and sema- 
phores used by the PDM. 


eee sss 


When you debug a multiprocessing application, each processor must have its 
own debugger. These debuggers can be invoked individually from the PDM 
command line. 


To invoke a debugger, use the SPAWN command. Here’s the basic format for 
this command: 


——=p> spawn emu5x [filename] [options] 


_] emubdx is the executable that invokes the debugger. In order to invoke a 
debugger, the PDM must be able to find the executable file for that debug- 
ger. The PDM will first search the current directory and then search the di- 
rectories listed with the PATH statement or path environment variable. 
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[J -n processor name supplies a processor name. You must use the —n 


option because the PDM uses processor names to identify the various 
debuggers that are running. The processor name can consist of up to eight 
alphanumeric characters or underscore characters and must begin with 
an alphanumeric character. Note that the name is not case sensitive. 


The processor name must match one of the names defined in your board 
configuration file (see Appendix C). For example, to invoke a debugger for 
a ’C5x that you had defined as CPU_A, you would enter: 


spawn emu5x -n CPU_A 


filename is an optional parameter that names an object file that the debug- 
ger loads into memory during invocation. The debugger looks for the file 
in the current directory; if the file isn’t in the current directory, you must sup- 
ply the entire pathname. 


If you don’t supply an extension for the filename, the debugger assumes 
that the extension is .out, unless you’re using multiple extensions; you 
must specify the entire filename if the filename has more than one exten- 
sion. 


—options supply the debugger with additional information. See Section 1.8 
for a complete list of debugger options. 


1.8 Debugger Options 


Debugger Options 


Table 1-1 lists the debugger options that you can use when invoking a debug- 
ger, and the subsections that follow the table describe these options. You can 
also specify filename and option information with the D-OPTIONS environ- 
ment variable (see Setting up the environment variables in your installation 


guide). 


Table 1-1. Summary of Debugger Options 


Option Brief Description 
—b[b] Select the screen size 


—d machinename Display the debugger on different 
machine (X Windows only) 


—f filename Identify a new board configura- 
tion file 

—i pathname Identify additional directories 

—mvversion Select the device version 


-p port address Identify the port address 


—profile Enter the profiling environment 
-s Load the symbol table only 

-t filename Identify a new initialization file 
-v Load without the symbol table 
—X Ignore DLOPTIONS 


Selecting the screen size (—b option) 


Debugger Tools 
All 


Emulator and simulator 


Emulator 


All 
Simulator 
EVM and emulator 


All, except when running 
under DOS 


All 
All 
All 
All 


By default, the debugger uses an 80-character-by-25-line screen. If you'd like 
to use a different screen size, the method for doing so varies, depending on 


the type of system that you’re using: 


[_} PC systems. You can use the —-b or —-bb option to select one of these pre- 


set screen sizes: 


-b = Screen size is 80 characters by 43 lines for EGA or VGA 


displays. 


-bb Screen size is 80 characters by 50 lines for a VGA display only. 
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(_} Sun systems. When you run multiple debuggers, the default screen size 
is a good choice because you can easily fit up to five default-size debug- 
gers on your screen. However, you can change the default screen size by 
using one of the —b options, which provides a preset screen size, or by re- 
sizing the screen at run time. (Note that when you are running a standa- 
lone debugger, you can also change the screen size by using one of these 
methods.) 


M@ Using apreset screen size. Use the —b or —bb option to select one of 
these preset screen sizes: 


-b Screen size is 80 characters by 43 lines. 
-bb Screen size is 80 characters by 50 lines. 


@ Resizing the screen at run time. You can resize the screen at run 
time by using your mouse to change the size of the operating-system 
window that contains the debugger. The maximum size of the debug- 
ger screen is 132 characters by 60 lines. 


Displaying the debugger on a different machine (—d option) 


This option is valid only when you are using the emulator or simulator. If you 
are using the X Windows System, you can use the -d option to display the de- 
bugger on a different machine than the one the program is running on. For ex- 
ample, if you are running a debugger on a machine called opie and you want 
the debugger display to appear on a machine called barney, use the following 
command to invoke the debugger: 


emu5x -d barney:0 


You can also specify a different machine by using the DISPLAY environment 
variable (see the installation guide for more information). If you use both the 
DISPLAY environment variable and —d, the —d option overrides DISPLAY. 


Identifying a new board configuration file (-f option) 


This option is valid only when you are using the emulator. The —-f option allows 
you to specify a board configuration file that will be used instead of board.dat. 
The format for this option is: 


-f filename 


Identifying additional directories (-i option) 


The -i option identifies additional directories that contain your source files. 
Replace pathnamewith an appropriate directory name. You can specify sever- 
al pathnames; use the —i option as many times as necessary. For example: 


sim5x -i pathname, -i pathnames -i pathname; . . . 


Debugger Options 


Using —i is similar to using the D_SRC environment variable (see Setting up 
the environment variables in the appropriate installation guide). If you name 
directories with both —iand D_SRC, the debugger first searches through direc- 
tories named with —i. The debugger can track a cumulative total of 20 paths 
(including paths specified with —i, D_SRC, and the debugger USE commana). 


Selecting the device version (—mv option) 


The —mv option is valid only when you are using the simulator. The —mv option 
tells the simulator to simulate the ’C50, ’C51, ’C52, or C53 memory map: 


—mv50 tells the simulator to simulate the >C50 memory map (default). 
—mv51 tells the simulator to simulate the C51 memory map. 
—mv52 tells the simulator to simulate the "C52 memory map. 
—mv53 tells the simulator to simulate the >C53 memory map. 


If you don’t use the —mv option, the simulator simulates the ’C50 memory map. 


Identifying the port address (—p option) 


The —p option is valid only when you are using the EVM or emulator. The —p 
option identifies the I/O port address that the debugger uses for 
communicating with the EVM or emulator. If you used the default switch 
settings, you don’t need to use the —p option. If you used nondefault switch 
settings, you must use -p. Refer to your entries in the Your Settings table 
in the appropriate installation guide; depending on your switch settings, 
replace port address with one of these values: 


Switch 1 Switch 2 Option 
on on —p 240 (optional) 
on off —p 280 
off on —p 320 
off off —p 340 


If you didn’t note the I/O switch settings, you can use a trial-and-error approach 
to find the correct —p setting. If you use the wrong setting, you will see an error 
message when you invoke the debugger. (See the appropriate installation 
guide for more information.) 


Entering the profiling environment (—profile option) 


This option is not valid when you’re running the debugger under DOS. The 
—profile option allows you to bring up the debugger in a profiling environment 
so that you can collect statistics about code execution. Note that only a subset 
of the basic debugger features is available in the profiling environment. 
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Loading the symbol table only (-s option) 


If you supply a filename when you invoke the debugger, you can use the —s 
option to tell the debugger to load only the file’s symbol table (without the file’s 
object code). This is similar to loading a file by using the debugger’s SLOAD 
command. 


Identifying a new initialization file (-t option) 


The —t option allows you to specify an initialization command file that will be 
used instead of init.cmd. The format for this option is: 


-—t filename 


Loading without the symbol table (-v option) 


The —v option prevents the debugger from loading the entire symbol table 
when you load an object file. The debugger loads only the global symbols and 
later loads local symbols as it needs them. This speeds up the loading time and 
consumes less memory. 


The -v option affects all loads, including those performed when you invoke the 
debugger and those performed with the LOAD command within the debugger 
environment. 


Ignoring D_OPTIONS (-x option) 


The —x option tells the debugger to ignore any information supplied with the 
D_OPTIONS environment variable (described in the installation guide). 


1.9 Exiting a Debugger or the PDM 
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To exit any version of the debugger, enter the following command from the 
COMMAND window of the debugger you want to close: 


quit 


You don’t need to worry about where the cursor is in the debugger 
window—just type. If a program is running, press to halt program execu- 
tion before you quit the debugger. 


If you’re running a standalone debugger under MS-Windows, you can exit the 
debugger by selecting the exit option from the MS-Windows menu bar. 


You can also enter QUIT from the command line of the PDM to quit all of the 
debuggers (and also close the PDM). 


Debugging ‘C5x Programs 


1.10 Debugging ’C5x Programs 


Debugging a program is a multiple-step process. These steps are described 
below, with references to parts of this book that will help you accomplish each 
step. 


Step 1 


Prepare a C program or as- See Section 1.6, Preparing 
sembly language program for Your Program for Debug- 
debugging. ging, page 1-12. 
BS) ) oy 7 
Ensure that the debugger has See Chapter 6, Defining a 
a valid memory map. Memory Map. 
BS) oS) 7 
Load the program's object file. See Section 7.3, Loading 
Object Code, page 7-10. 
Step 4 yy 


Runtheloadedfile. Youcanrun See Section 7.5, Running 


the entire program, run parts of Be Programs, on page 


the program, or single-step 
through the program. 


Stop the program at critical See Chapter 9, Using Soft- 


points and examine important ware Breakpoints, _ and 
information Chapter 8, Managing Data. 


If you find minor problems in See Modifying assembly lan- 


your code, you can temporari- guage code on page 7-5. 
ly solve them with patch 
assembly. 


Once you have decided what changes must be made to your 
program, exit the debugger, edit your source file, and return to 
Step 1. 
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Using the Parallel Debug Manager 


The TMS320C5x emulation system is a true multiprocessing debugging 
system. It allows you to debug your entire application by using the parallel 
debug manager (PDM). The PDM is acommand shell that controls and coordi- 
nates multiple debuggers. This chapter describes the functions that you can 
perform with the PDM. 


Refer to Chapter 1, Overview of a Code Development and Debugging System, 
for information about invoking the PDM and debuggers. 
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Identifying Processors and Groups 


You can send commands to an individual processor or to a group of proces- 
sors. To do this, you must assign names to the individual processors or to 
groups of processors. Individual processor names are assigned when you in- 
voke the individual debuggers; you can assign group names with the SET 
command after the individual processor names have been assigned. 


eT | 
Note: 


Each debugger that runs under the PDM must have a unique processor 
name. The PDM does not keep track of existing processor names. When you 
send acommand to a debugger, the PDM will validate the existence of a de- 
bugger invoked with that processor name. 


Assigning names to individual processors 
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You must associate each debugger within the multiprocessing system with a 
unique name, referred to as a processor name. The processor name is used 
for: 


[_] Identifying a processor to send commands to. 


[_.} Assigning a processor to a group. 


[_] Setting the default prompts for the associated debuggers. For example, 
if you invoke a debugger with a processor name of CPU_A, that debug- 
ger’s prompt will be CPU_A>. 


[_] Identifying the individual debuggers on the screen (Sun systems only). 
The processor name that you assign will appear at the top of the operating- 
system window that contains the debugger. Additionally, if you turn one of 
the windows into an icon, the icon name is the same as the processor 
name that you assigned. 


To assign a processor name, you can use the —n option when you invoke a de- 
bugger. For example, to name one of the ’C5x processors CPU_B, use the 
following command to invoke the debugger: 


spawn emu5x -n CPU_B 


From this point onward, whenever you need to identify this debugger, you can 
identify it by its processor name, CPU_B. 


The processor name that you supply can consist of up to eight alphanumeric 
characters or underscore characters and must begin with an alphabetic char- 
acter. Note that the name is not case sensitive. The processor name must 
match one of the names defined in your board configuration file (refer to 
Appendix C, Describing Your Target System to the Debugger). 


Organizing processors into groups 


Identifying Processors and Groups 


Processors can be organized into groups; these groups are identified by 
names defined with the SET command. Each processor can belong to any 
group, all groups, or a group of its own. Figure 2—1 (a) shows an example of 
processors that could exist in a system, and Figure 2—1 (b) illustrates three ex- 
amples of named groups. GROUP1 contains two processors, GROUP2 con- 
tains four processors, and GROUPS contains five processors. 


Figure 2—1. Grouping Processors 


(a) All possible processors in a system 
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(b) Examples of how processors could be grouped 
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To define and manipulate software groupings of named processors, use the 
SET and UNSET commands. 


_] Defining a group of processors 


To define a group, use the SET command. The format for this commandis: 


set [group name [= list of processor names] | 


This command allows you to specify a group name and the list of proces- 
sors you wantinthe group. The group name can consist of up to 128 alpha- 
numeric characters or underscore characters. 


Using the Parallel Debug Manager 2-3 


Identifying Processors and Groups 


2-4 


For example, to create the GROUP1 group illustrated in Figure 2—1 (b), 
you could enter the following on the PDM command line: 


set GROUP1 = CPU_A CPU_C 


The result is a group called GROUP1 that contains the processors named 
CPU_Aand CPU_C. Note that the order in which you add processors to a 
group is the same order in which commands will be sent to the members of 
that group. 


Seiting the default group 


Many of the PDM commands can be sent to groups; if you often send com- 
mands to the same group and you want to avoid typing the group name 
each time, you can assign a default group. 


To set the default group, use the SET command with a special group name 
called dgroup. For example, if you want the default group to contain the 
processors called CPU_B, CPU_D, and CPU_E, enter: 


set dgroup = CPU_B CPU_D CPU_E 


The PDM will automatically send commands to the default group when 
you don’t specify a group name. 


Modifying an existing group or creating a group based on another 
group 


Once you've created a group, you can add processors to it by using the 
SET command and preceding the existing group name with a dollar sign 
($) in the list of processors. You can also use a group as part of another 
group by preceding the existing group’s name with a dollar sign. The dollar 
sign tells the PDM to use the processors listed previously in the group as 
part of the new list of processors. 


Suppose GROUPA contained CPU_C and CPU_D. If you wanted to add 
CPU_E to the group, you'd enter: 


set GROUPA = $GROUPA CPU_E 


After entering this command, GROUPA would contain CPU_C, CPU_D, 
and CPU_E. 


If you decided to send numerous commands to GROUPA, you could make 
it the default group: 


set dgroup = $GROUPA 


Identifying Processors and Groups 


(_] Listing all groups of processors 
To list all groups of processors in the system, use the SET command with- 
out any parameters: 
set 
The PDM lists all of the groups and the processors associated with them: 


GROUP1 *CPU_A. (CPUL_C” 
GROUPA "CPU_C CPU_D CPU_E” 
dgroup "CPU_C CPU_D CPU_E” 


You can also list all of the processors associated with a particular group by 
supplying a group name: 


set dgroup 
dgroup "CPU_C CPU_D CPU_E 


= 
3 


(_] Deleting a group 
To delete a group, use the UNSET command. The format for this com- 
mand is: 


unset group name 


You can use this command in conjunction with the SET command to re- 
move a particular processor from a group. For example, suppose 
GROUPB contained CPU_A, CPU_C, CPU_D, and CPU_E. If youwanted 
to remove CPU_E, you could enter: 


unset GROUPB 
set GROUPB = CPU_A CPU_C CPU_D 


If you want to delete all of the groups you have created, use the UNSET 
command with an asterisk instead of a group name: 


unset * 
Note that the asterisk does not work as a wild card. 


TS 


Note: 


When you use UNSET ~* to delete all of your groups, the default group 
(dgroup) is also deleted. As a result, if you issue a command such as PRUN 
and don’t specify a group or processor, the command will fail because the 
PDM can’t find the default group name (dgroup). 
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2.2 Sending Debugger Commands to One or More Debuggers 
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The SEND command sends a debugger command to an individual processor 
or to agroup of processors. The command is sent directly to the command in- 
terpreter of the individual debuggers. You can send any valid debugger com- 
mand string. 


The syntax for the SEND command is: 
send [-r] [-g {group| processor name}| debugger command 


[_} The -g option specifies the group or processor that the debugger com- 
mand should be sent to. If you don’t use this option, the command is sent 
to the default group (dgroup). 


(_} The -t (return) option determines when control returns to the PDM com- 
mand line: 


HM Without -t, control is not returned to the command line until each de- 
bugger in the group finishes running code. Any results that would be 
printed in the COMMAND window of the individual debuggers will also 
be echoed in the PDM command window. These results will be dis- 
played by processor. For example: 
send ?pc 
[CPU_C] 0x400A 
[CPU_D] 0x4010 
If you wantto break out of asynchronous command and regain control 
ofthe PDM commandline, press in the PDM window. This 
will return control to the PDM command line. However, no debugger 
executing the command will be interrupted. 


H@ With-t, control is returned to the command line immediately, even if a 
debugger is still executing a command. When you use -r, you do not 
see the results of the commands that the debuggers are executing. 


The -r option is useful when you want to exit from a debugger but not 
from the PDM. When you send the QUIT command to a debugger or 
group of debuggers without using the -r command, you will not be able 
to enter another PDM command until all debuggers to which QUIT 
was sent to finish quitting; the PDM waits for a response from all of the 
debuggers have finishedDecember 1993 quitting. By using —r, you can 
gain immediate control of the PDM and continue sending commands 
to the remaining debuggers. 


The SEND command is useful for loading a common object file into a group 
of debuggers. For example, to load a file called test.out into the debuggers 
contained in GROUP_A, you could use the following command: 


send -g GROUP_A load test.out 


Running and Halting Code 


2.3. Running and Halting Code 


The PRUN, PRUNF, and PSTEP commands synchronize the debuggers to 
cause the processors to begin execution at the same real time. 


[|_| PRUNF starts the processors running free, which means they are discon- 
nected from the emulator. 


[_.} PRUN starts the processors running under the control of the emulator. 


|_|] PSTEP causes the processors to single-step synchronously through as- 
sembly language code with interrupts disabled. 


The formats for these commands are: 

prunf [-g {group | processor name}] 

prun [-r] [-g {group | processor name}] 
pstep [-g {group | processor name}| [count] 


(_} The -g option identifies the group or processor that the command should 
be sent to. If you don’t use this option, the command is sent to the default 
group (dgroup). 


(_] The -r (return) option for the PRUN command determines when control 
returns to the PDM command line: 


H Without -f, control is not returned to the command line until each 
debugger in the group finishes running code. If you want to break out 
of a synchronous command and regain control of the PDM command 
line, press in the PDM window. This will return control to 
the PDM command line. However, no debugger executing the com- 
mand will be interrupted. 


H@ With-tr, control is returned to the command line immediately, even if a 
debugger is still executing acommand. You can type new commands, 
but the processors can’t execute the commands until they finish with 
the current command; however, you can perform PHALT, PESC, and 
STAT commands when the processors are still executing. 


(_] You can specify a count for the PSTEP command so that each processor 
in the group will step for count number of times. 


Note: 


If the current statement that a processor is pointing to has a breakpoint, that 
processor will not step synchronously with the other processors when you 
use the PSTEP command. However, that processor will still single-step. 
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Halting processors at the same time 


You can use the PHALT command after you enter a PRUNF command to stop 
an individual processor or a group of processors (global halt). Each processor 
in the group is halted at the same real time. The syntax for the PHALT com- 
mand is: 


phalt [-g {group | processor name}] 


Sending ESCAPE to all processors 


Use the PESC command to send the escape key to an individual processor 
or to a group of processors after you execute a PRUN command. Entering 
PESC is essentially like typing an escape key in all of the individual debuggers. 
However, the PESC command is asynchronous; the processors don’t halt at 
the same real time. When you halt a group of processors, the individual pro- 
cessors are halted in the order in which they were added to the group. 


The syntax for this command is: 


pesc [-g {group | processor name}] 


Finding the execution status of a processor or a group of processors 
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The STAT command tells you whether a processor is running or halted. If a pro- 
cessor is halted when you execute this command, then the PDM also lists the 
current PC value for that processor. The syntax for the command is: 


stat [-g {group | processor name}] 


For example, to find the execution status of all of the processors in GROUP_A 
after you’ve executed a global PRUN, enter: 


stat -g GROUP_A 


After entering this command, you'll see something similar to this in the PDM 
window: 


[CPU_C] Running 
[CPU_D] Halted PC=201A 
[CPU_E] Running 


Entering PDM Commands 


2.4 Entering PDM Commands 


The PDM provides a flexible command-entry interface that allows you to: 


Execute PDM commands from a batch file 

Record the information shown in the PDM display area 
Conditionally execute or loop through PDM commands 

Echo strings to the PDM display area 

Pause command execution 

Repeat previously entered commands (use the command history) 


OUUOUUOUU 


This section describes the PDM commands that you can use to perform these 
tasks. 


Executing PDM commands from a batch file 


The TAKE command tells the PDM to execute commands from a batch file. 
The syntax for the PDM version of this command is: 


take batch filename 


The batch filename must have a .pdm extension, or the PDM will not be able 
to read the file. If you don’t supply a pathname as part of the filename, the PDM 
first looks in the current directory and then searches directories named with 
the D_DIR environment variable. 


The TAKE command is similar to the debugger version of this command (de- 
scribed on page 5-17). However, there are some differences when you enter 
TAKE as a PDM command instead of a debugger command. 


|_| Similarities. As with the debugger version of the TAKE command, you 
can nest batch files up to 10 deep. 


|] Differences. Unlike the debugger version of the TAKE command: 


M@ There is no suppress-echo-flag parameter. Therefore, all command 
output is echoed to the PDM window, and this behavior cannot be 
changed. 


HM To halt batch-file execution, you must press instead of 
ESC). 


The batch file must contain only PDM commands (no debugger com- 
mands). 


The TAKE command is advantageous for executing a batch file in which you 
have defined often-used aliases. Additionally, you can use the SET command 
in a batch file to set up group configurations that you use frequently, and then 
execute that file with the TAKE command. You can also put your flow-control 
commands (described on page 2-10) in a batch file and execute the file with 
the TAKE command. 
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Recording information from the PDM display area 


By using the DLOG command, you can record the information shown in the 
PDM display area into a log file. This command is identical to the debugger 
DLOG command described on page 5-6. 


(_] To begin recording the information shown in the PDM display area, use: 
dlog filename 


This command opens a log file called filename that the information is 
recorded into. If you plan to execute the log file with the TAKE command, 
the filename must have a .pdm extension. 


[_} To end the recording session, enter: 
dlog close 


If necessary, you can write over existing log files or append additional informa- 
tion to existing files. The extended format for the DLOG command is: 


dlog filename [,{a | w}] 
The optional parameters control how the log file is created and/or used: 


_] Appending to an existing file. Use the a parameter to open an existing 
file and append the information in the display area. 


(_] Writing over an existing file. Use the w parameter to open an existing 
file and write over the current contents of the file. Note that this is the 
default action if you specify an existing filename without using either the 
a or w options; you will lose the contents of an existing file if you don’t use 
the append (a) option. 


Controlling PDM command execution 


You can control the flow of PDM commands in a batch file or interactively. With 
the IF/ELIF/ELSE/ENDIF or LOOP/BREAK/CONTINUE/ENDLOOP flow- 
control commands, you can conditionally execute debugger commands or set 
up a looping situation, respectively. 


[_} To conditionally execute PDM commands, use the IF/ELIF/ELSE/ENDIF 
commands. The syntax is: 


if expression 
PDM commands 
[elif expression 
PDM commands] 
[else 

PDM commands] 
endif 
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Milf the expression for the IF is nonzero, the PDM executes all com- 
mands between the IF and ELIF, ELSE, or ENDIF. 


@ The ELIF is optional. If the expression for the ELIF is nonzero, the 
PDM executes all commands between the ELIF and ELSE or ENDIF. 


HM TheELSE is optional. If the expressions for the IF and ELIF (if present) 
are false (zero), the PDM executes the commands between the ELSE 
and ENDIF. 


(_} To setup a looping situation to execute PDM commands, use the LOOP/ 
BREAK/CONTINUE/ENDLOOP commands. The syntax is: 


loop Boolean expression 
PDM commands 

[break] 

[continue] 

endloop 


The PDM version of the LOOP command is different from the debugger 
version of this command (described on page 5-20). Instead of accepting 
any expression, the PDM version of the LOOP command evaluates only 
Boolean expressions. If the Boolean expression evaluates to true (1), the 
PDM executes all commands between the LOOP and BREAK, 
CONTINUE, or ENDLOOP. If the Boolean expression evaluates to false 
(0), the loop is not entered. 


H The optional BREAK command allows you to exit the loop without hav- 
ing to reach the ENDLOOP. This is helpful when you are testing a 
group of processors and want to exit if an error is detected. 


HM The CONTINUE command, which is also optional, acts as a goto and 
returns command flow to the enclosing LOOP command. CONTINUE 
is useful when the part of the loop that follows is complicated, and re- 
turning to the top of the loop avoids further nesting. 


You can enter the flow-control commands interactively or include the com- 
mands ina batch file that is executed by the TAKE command. When you enter 
LOOP or IF from the PDM command line, a question mark (?) prompts you for 
the next entry: 

PDM:11>>aif $i > 10 

?echo ERROR IN TEST CASE 

?endif 

ERROR IN TEST CASE 


PDM:12>> 
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The PDM continues to prompt you for input using the ? until you enter ENDIF 
(for an IF command) or ENDLOOP (for a LOOP command). After you enter 
ENDIF or ENDLOOP, the PDM immediately executes the IF or LOOP com- 
mand. 


If you are in the middle of interactively entering a LOOP or IF statement and 
want to abort it, type ©). 


You can use the IF/ENDIF and LOOP/ENDLOOP commands together to per- 
form a series of tests. For example, within a batch file, you can create a loop 
like the following (the SET and @ commands are described in Section 2.8, 
page 2-18): 

set i = 10 Set the counter (i) to 10 
loop $i > 0 Loop while i is greater than 0 


test commands 


if $k > 500 Test for error condition 

echo ERROR ON TEST CASE 8 Display an error message 
endif 

@i=Si-1 Decrement the counter 
endloop 


You can record the results of this loop in a log file (refer to page 2-10) to 
examine which test cases failed during the testing session. 


Echoing strings to the PDM display area 


You can display a string inthe PDM display area by using the ECHO command. 
This command is especially useful when you are executing a batch file or run- 
ning a flow-control command such as IF or LOOP. The syntax for the command 
is: 


echo _ string 
This displays the string in the PDM display area. 


You can also use ECHO to show the contents of a system variable (system 
variables are described in Section 2.8): 


echo $var_procl 
34 


The PDM version of the ECHO command works exactly the same as the 
debugger version described on page 5-18, except that you can use the PDM 
version outside of a batch file. 
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Pausing command execution 


Sometimes you may want the PDM to pause while it’s running a batch file or 
when it’s executing a flow control command such as LOOP/ENDLOOP. Paus- 
ing is especially helpful in debugging the commands in a batch file. 


The syntax for the PAUSE command is: 
pause 


When the PDM reads this command in a batch file or during a flow control com- 
mand segment, the PDM stops execution and displays the following message: 


<< pause - type return >> 


To continue processing, press @). 


Using the command history 


The PDM supports a command history that is similar to the UNIX command 
history. The PDM prompt identifies the number of the current command. This 
number is incremented with every command. For example, PDM:12>> indi- 
cates that eleven commands have previously been entered, and the PDM is 
now ready to accept the twelfth command. 


The PDM command history allows you to re-enter any of the last twenty com- 
mands: 


[_] To repeat the last command that you entered, type: 
"! 


[_] To repeat any of the last twenty commands, use the following command: 
!number 


The numberis the number of the PDM prompt that contains the command 
that you want to re-enter. For example, 


PDM:100>>echo hello 
hello 

PDM:101>>echo goodbye 
goodbye 

PDM:102>>!100 

echo hello 

hello 


Notice that the PDM displays the command that you are re-entering. 
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[_] An alternate way to repeat any of the last twenty commands is to use: 
'string 


This command tells the PDM to execute the last command that began with 
string. For example, 


PDM:103>>pstep -g GROUPA 
PDM:104>>send -g GROUPA ?pc 
[CPU_C] 0x4000 

[CPU_D] 0x4004 

PDM:103>>pstep -g GROUPB 
PDM:104>>send -g GROUPB ?pc 
[CPU_A] O0x401A 

[CPU_E] 0x4014 

PDM:105>>!p 

pstep -g GROUPB 


_] To see alist of the last twenty commands that you entered, type: 
history 
The command history for the PDM works differently from that of the debugger 


(described on page 5-5); the and keys have no command-history 
meaning for the PDM. 


Defining Your Own Command Strings 


2.5 Defining YourOwn Command Strings 


The ALIAS command provides a shorthand method of entering often-used 
commands or command sequences. The UNALIAS command deletes one or 
more ALIAS definitions. The syntax for the PDM version of each of these com- 
mands is: 


alias [alias name [, *>command string’]| 
unalias {alias name | *} 


The PDM versions of the ALIAS and UNALIAS commands are similar to the 
debugger versions of these commands. You can: 


[_] Include several commands in the command string by separating the indi- 
vidual commands with semicolons. 


[_] Define parameters in the command string by using a percent sign and a 
number (%1, %2, etc.) to represent a parameter whose value will be sup- 
plied when you execute the aliased command. 


[_] List all currently defined PDM aliases by entering ALIAS with no parame- 
ters. 


[|_|] Find the definition of a PDM alias by entering ALIAS with only an alias- 
name parameter. 


__} Nest alias definitions. 


[_.] Redefine an alias. 


[_] Delete a single PDM alias by supplying the UNALIAS command with an 
alias name, or delete all PDM aliases by entering UNALIAS *. 


Like debugger aliases, PDM alias definitions are lost when you exit the PDM. 
However, individual commands within a PDM command string don’t have an 
expanded-length limit. 


For more information about these features, refer to Section 5.5, Defining Your 
Own Command Strings. 


The PDM version of this command is especially useful for aliasing often-used 
command strings involving the SEND and SET commands. 


(_] You can use the ALIAS command to create PDM versions of debugger 
commands. For example, the ML debugger command lists the memory 
ranges that are currently defined. To make a PDM version of the ML com- 
mand to list the memory ranges of all the debuggers in a particular group, 
enter: 


alias ml, "send -g %1 ml” 
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You could then list the memory maps of a group of processors such as 
those in group GROUPA: 


ml GROUPA 


The ALIAS command can be helpful if you frequently change the default 
group. For example, suppose you plan to switch between two groups. You 
can set up the following alias: 

alias switch, "set dgroup $%1; set prompt %1” 

The %1 parameter will be filled in with the group information that you enter 
when you execute SWITCH. Notice that the %1 parameter is preceded by 
a dollar sign ($) to set up the default group. The dollar sign tells the PDM to 
evaluate (take the list of processor names defined in the group instead of 
the actual group name). However, to change the prompt, you don’t want 
the PDM to evaluate (use the processors associated with the group name 
as the prompt)—you just want the group name. As a result, you don’t need 
to use the dollar sign when you want to use only the group name. 


Assume that GROUPS contains CPU_A, CPU_B, and CPU_D. To make 
GROUPS the current default group and make the PDM prompt the same 
name as your default group, enter: 

switch GROUP3 


This causes the default group (dgroup) to contain CPU_A, CPU_B, and 
CPU_D, and changes the PDM prompt to GROUP3:x>>. 


2.6 Entering Operating-System Commands 


The SYSTEM command provides you with a method of entering operating- 
system commands. The format for the PDM version of this command is: 


system operating-system command 


The SYSTEM command is similar to the debugger’s SYSTEM command (de- 
scribed on page 5-24), but there are some differences. 


(_} Similarities. You can enter operating-system commands without having 


to leave the primary environment (in this case, the PDM) and without hav- 
ing to open another operating-system window. 


(_] Differences. Unlike the debugger version of the SYSTEM command: 


M@ The PDM version of the SYSTEM command cannot be entered with- 
out an operating-system command parameter. Therefore, you cannot 
use the command to open a shell. 


HM There is no flag parameter; command output is always displayed in 
the PDM window. 


Understanding the PDM’s Expression Analysis 


2.7 Understanding the PDM’s Expression Analysis 


The PDM analyzes expressions differently than individual debuggers do (ex- 
pression analysis for the debugger is described in Chapter 14, Basic Informa- 
tion About C Expressions). The PDM uses a simple integral expression ana- 
lyzer. You can use expressions to cause the PDM to make decisions as part 
of the @ command and the flow control commands (described on pages 2-18 
and 2-10, respectively). 


Note that you cannot evaluate string variables with the PDM expression ana- 


lyzer. You can evaluate only constant expressions. 


Table 2-1 summarizes the PDM operators. The PDM interprets the operators 
in the order that they’re listed in Table 2—1 (left to right, top to bottom). 


Table 2-1. PDM Operators 


Operator 
() 

/ 

+ 


<< 


Definition 

take highest precedence 
division 

addition (binary) 
left shift 

less than 
greater than 

is equal to 
bitwise AND 
bitwise OR 
logical OR 


Operator 


Definition 
multiplication 
modulo 

subtraction (binary) 
complement 

right shift 

less than or equal to 
greater than or equal to 
is not equal to 
bitwise exclusive-OR 
logical AND 
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2.8 Using System Variables 


You can use the SET, @, and UNSET commands to create, modify, and delete 
system variables. In addition, you can use the SET command with system- 
defined variables. 


Creating your own system variables 


The SET command lets you create system variables that you can use with 
PDM commands. The syntax for the SET command is: 


set [variable name [= string] | 


The variable name can consist of up to 128 alphanumeric characters or under- 
score characters. 


For example, suppose you have an array that you want to examine frequently. 
You can use the SET command to define a system variable that represents 
that array value: 


set result = ar1l[0] + 100 


In this case, result is the variable name, and ar1[0] + 100 is the expression 
that will be evaluated whenever you use the variable result. 


Once you have defined result, you can use it with other PDM commands such 
as the SEND command: 


send CPU_D ? $result 


The dollar sign ($) tells the PDM to replace result with ar1[0] + 100 (the string 
defined in result) as the expression parameter for the ? command. You must 
precede the name of asystem variable with a $ when you wantto use the string 
value you defined with the variable as a parameter. 


You can also use the SET command to concatenate and substitute strings. 


(_] Concatenating strings 


The dollar sign followed by a system variable name enclosed in braces 
( { and } ) tells the PDM to append the contents of the variable name to a 
string that precedes or follows the braces. For example: 


set k = Hel Set k to the string Hel 
set i = ${k}lo ${k}en Concatenate the contents of k before 

lo and en and set the result to i 
echo $i Show the contents of i 
Hello Helen 
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(_] Substituting strings 


You can substitute defined system variables for parts of variable names or 
strings. This series of commands illustrates the substitution feature: 


set err0 = 25 Set err0 to 25 
set j = 0 Set j to 0 
echo Serr$j Show the value of $err$j — $errO > 25 
25 

Note that substitution stops when the PDM detects recursion (for example, 
$k = k). 


Assigning a variable to the result of an expression 


The @ (substitute) command is similar to the SET command. You can use the 
@ command to assign the result of an expression to a variable. The syntax for 
the @ command is: 


@ variable name = expression 


The following series of commands illustrates the differences between the @ 
command and the SET command. Assume that mask1 equals 36 and mask2 
equals 47. 


set mask3 = $mask1+$mask2 Set mask3 to the contents of mask1 
plus the contents of mask2 


echo $mask3 Show the contents of mask3 

36+47 

@ mask3 = $mask1+$mask2 Set mask3 to the result of the 
expression $mask1+$mask2 

echo $mask3 Show the contents of mask3 

83 


Notice the difference between the two commands. The @ command evaluates 
the expression and assigns the result to the variable name. 


The @ command is useful in setting loop counters. For example, you can ini- 
tialize a counter with the following command: 


@j=o0 
Inside the loop, you can increment the counter with the following statement: 
@j=$jt+i 

Changing the PDM prompt 


The PDM recognizes a system variable called prompt. You can change the 
PDM prompt by setting the prompt variable to a string. For example, to change 
the PDM prompt to 3PROCs, enter: 


set prompt = 3PROCs 
After entering this command, the PDM prompt will look like this: 3PROCs:x>>. 
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Checking the execution status of the processors 


In addition to displaying the execution status of a processor or group of proces- 
sors, the STAT command (described on page 2-8) sets a system variable 
called status. 


[_] If allof the processors in the specified group are running, the status vari- 
able is set to 1. 


[_] If one or more of the processors in the group Is halted, the status variable 
is set to 0. 


You can use this variable when you want an instruction loop to execute until 
a processor halts: 


loop stat == 
send ?pc 


Listing system variables 


To list all system variables, use the SET command without parameters: 
set @) 
You can also list the contents of a single variable. For example, 


set j @ 
5 #VOOe 


Deleting system variables 


To delete a system variable, use the UNSET command. The format for this 
command is: 


unset variable name 


If you want to delete all of the variables you have created and any groups you 
have defined (as described on page 2-3), use the UNSET command with an 
asterisk instead of a variable name: 


unset * 


EOESE__<—_¥_¥—_5<5<__<$<_$_<$$ 
Note: 


When you use UNSET * to delete all of your system variables and processor 
groups, variables such as prompt, status, and dgroup are also deleted. 
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2.9 Evaluating Expressions 


The debugger includes an EVAL command that evaluates an expression (see 
Section 8.2, Basic Commands for Managing Data, for more information about 
the debugger version of the EVAL command). The PDM has a similar com- 
mand called EVAL that you can send to a processor or a group of processors. 
The EVAL command evaluates an expression in a debugger and sets a vari- 
able to the result of the expression. The syntax for the PDM version of the 
EVAL command is: 


eval [-g {group | processor name}] variable name=expressior|, format] 


[_] The -g option specifies the group or processor that EVAL should be sent 
to. If you don’t use this option, the command is sent to the default group 


(dgroup). 


[_} When you send the EVAL command to more than one processor, the PDM 
takes the variable namethat you supply and appends a suffix for each pro- 
cessor. The suffix consists of the underscore character (_) followed by the 
name that you assigned the processor. That way, you can differentiate be- 
tween the resulting variables. 


[_.] The expression can be any expression that uses the symbols described 
in Section 2.7. 


[|_| When you use the optional format parameter, the value that the variable 
is set to will be in one of the following formats: 


Parameter Result Parameter Result 


7 Default for the data type fe) Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


Suppose the program that CPU_A is running has two variables defined: j is 
equal to 5, and k is equal to 17. Also assume that the program that CPU_B is 
running contains variables j and k: j is equal to 12, and k is equal to 22. 


set dgroup = CPU_A CPU_B 
eval val = j +k @® 

set 

dgroup "CPU_A CPU_B” 


val_CPULA "22" 
val_CPU_B "34" 


Notice that the PDM created a system variable for each processor: 
val_CPU_A for CPU_A and val_CPU_B for CPU_B. 
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Chapter 3 


An Introductory Tutorial 
to the C Source Debugger 


This chapter provides a step-by-step, hands-on demonstration of the ’'C5x C 
source debugger’s basic features. This is not the kind of tutorial that you can 
take home to read—t is effective only if you're sitting at your terminal, perform- 
ing the lessons in the order that they’re presented. The tutorial contains two 
sets of lessons (11 in the first, 13 in the second) and takes about one hour to 
complete. 


Topic Page 
How to use this tutorial 3-2 
A note about entering commands 3-2 
An escape route (just in case) 3-3 
Invoke the debugger and load the sample program’s object code 3-3 
Take a look at the display. . . 3-4 
Whait’s in the DISASSEMBLY window? 3-5 
Select the active window 3-5 
Resize the active window 3-7 
Zoom the active window 3-8 
Move the active window 3-9 
Scroll through a window’s contents 3-10 
Display the C source version of the sample file 3-11 
Execute some code 3-11 
Become familiar with the three debugging modes 3-12 
Open another text file, then redisplay a C source file 3-14 
Use the basic RUN command 3-14 
Set some breakpoints 3-15 
Benchmark a section of code 3-16 
Watch some values and single-step through code 3-17 
Run code conditionally 3-19 
WHATIS that? 3-20 
Clear the COMMAND window display area 3-21 
Display the contents of an aggregate data type 3-21 
Display data in another format 3-24 
Change some values 3-26 
Define a memory map 3-27 
Define your own command string 3-28 
Close the debugger 3-28 
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How to Use This Tutorial / A Note About Entering Commands 


How to use this tutorial 


This tutorial contains three basic types of information: 


Primary actions Primary actions identify the main lessons in the 
tutorial; they're boxed so that you can find them 
easily. A primary action looks like this: 


Make the CPU window the active window: 


win CPU 


Important information In addition to primary actions, important infor- 
mation ensures that the tutorial works correctly. 
Important information is marked like this: 


| Important! | The CPU window should still be 


active from the previous step. 


Alternative actions Alternative actions show additional methods for 
performing the primary actions. Alternative 
actions are marked like this: 


Try This: | another way to display the current 
code in MEMORY is to show memory begin- 
ning from the current PC. . . 


| Important! | This tutorial assumes that you have correctly and completely 
installed your debugger (including invoking any files or DOS commands as in- 
structed in the installation guide). 


A note about entering commands 
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Whenever this tutorial tells you to type a debugger command, just type—the 
debugger automatically places the text on the command line. You don’t have 
to worry about moving the cursor to the command line; the debugger takes 
care of this for you. (There are a few instances when this isn’t true—for exam- 
ple, when you're editing data in the CPU or MEMORY window—but this is 
explained later in the tutorial.) 


Also, you don't have to worry about typing commands in uppercase or lower- 
case—either is fine. There are a few instances when a command's parame- 
ters must be entered in uppercase, and the tutorial points this out. 


An Escape Route / Invoke the Debugger and Load the Sample Program’s Object Code 


An escape route (just in case) 


The steps in this tutorial create a path for you to follow. The tutorial won’t 
purposely lead you off the path. But sometimes when people use new 
products, they accidently press the wrong key, push the wrong mouse button, 
or mistype a command. Suddenly, they’re off the path without any idea of 
where they are or how they got there. 


This probably won’t happen to you. But, if it does, you can almost always get 
back to familiar ground by pressing . If you were running a program when 
you pressed (SC), you should also type RESTART @). Then go back to the 
beginning of whatever lesson you were in and try again. 


Invoke the debugger and load the sample program’s object code 


Included with the debugger is a demonstration program named sample. This 
lesson shows you how to invoke the debugger and load the sample program. 


| Important! | If you are using the EVM or emulator, this step assumes that you 
are using the default I/O address or that you have identified the I/O address 
with the D_OPTIONS environment variable (as described in the individual in- 
stallation guides). 


Invoke the debugger and load the sample program: 
Q) For the emulator, enter: 

emu5x c:\c5xh11\sample 
( For the EVM, enter: 

evm5x c:\c5xh11\sample 


1 For the simulator, enter: 


sim5x c:\sim5x\sample 
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Take a Look at the Display 


Take a look at the display. . . 


Now you should see a display similar to this (it may not be exactly the same, 
but it should be close). 


menu bar with 


P Load Break Watch Memor: Color MoDe Analyi Pin Run=F5 Step=F8 Next=F10 

pulldown menus z. arya E 

-—DISASSEMBLY 

20cf b£f08 int0O: ARO, #08alh OO000005£ 
current PC j Sea bf09 anne saiteners OTEEOUES 

eat = 

(highlighted) d 

20d3 b£00 10) 00000005 

20d4 beAa7 SXM 20c£E 

#2143h O8ab 

reverse assembly l #1 08a5 


of memory contents i 20dch, EQ 00a4 


20e0h, *, AR1 08a4 
: main, *,AR1 2610 
register contents abort, *, ARI PE 0038 
#2143h o1fe 
#0 0000 
* 08ab 
#1 ffel 
AR2,*, AR2 0800 


: So MEMORY 
COMMAND window || tMS320c5x Revision 1 0000 0000 
display area 0008 0000 
Loading sample.out 0010 O8ab 


memory contents SARS EDSTERIOSUSG 


Done 


command line >|| >>> 


_] If you don’t see a display, then your debugger or board may not be in- 
stalled properly. Go back through the installation instructions and be sure 
that you followed each step correctly; then reinvoke the debugger. 


_] If you do see a display, check the first few lines of the DISASSEMBLY 
window. |f these lines aren’t the same—f, for example, they show ADD 
instructions or say Invalid address—then enter the following commands 
on the debugger command line. (Just type; you don’t have to worry about 
where the cursor is.) 

1) Reset the ’C5x processor: 
reset 

2) Load the sample program again: 
load c:\c5xh11\sample (EVM and emulator) 
load c:\sim5x\sample (simulator) 

_] After reset, if you see adisplay and the first few lines of the DISASSEMBLY 
window still show ADD instructions or say Invalid address after resetting 
the ’C5x processor, your EVM or emulator board may not be installed 


snugly. Check your board to see if it is correctly installed, and re-enter the 
commands above. 
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What's in the DISASSEMBLY Window? / Select the Active Window 


What’s in the DISASSEMBLY window? 


The DISASSEMBLY window always shows the reverse assembly of memory 
contents; in this case, it shows an assembly language version of sample.out. 
The MEMORY window displays the current contents of memory. Because you 
loaded the object file sample.out when you invoked the debugger, memory 
contains the object code version of the sample file. 


This tutorial step demonstrates that the code shown in the DISASSEMBLY 
window corresponds to memory contents. Initially, memory is displayed start- 
ing at address 0; if you look at the first line of the DISASSEMBLY window, you'll 
see that its display starts at address Ox20ctf. 


Modify the MEMORY display to show the same object code that is dis- 
played in the DISASSEMBLY window: 


mem O0x20cf@prog 


Notice that the first column in the DISASSEMBLY window corresponds to the 
addresses in the MEMORY window; the second column in the DISASSEMBLY 
window corresponds to the memory contents displayed in the MEMORY 
window. 


Try This: 


The ’C5x has separate program and data spaces. You can access 
either program or data memory by following the location with @prog for 
program memory or @data for data memory. If you'd like to see the contents 
of location 0x0800 in data memory, enter: 


mem 0x800@data 


Try This: | Another way to display the current code in MEMORY is to show 
memory beginning from the current PC: 


mem PC@prog 


Select the active window 


This lesson shows you how to make a window into the active window. You can 
move and resize any window; you can close some windows. Whenever you 
type a command or press a function key to move, resize, or close a window, 
the debugger must have some method of understanding which window you 
want to affect. The debugger does this by designating one window at a time 
to be the active window. Any window can be the active window, but only one 
window at a time can be active. 


lesson continues on the next page > 
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Select the Active Window 
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UW 


Make the CPU window the active window: 


win CPU 


| Important! | Notice the appearance of the CPU window (especially its 
borders) in contrast to the other, inactive windows. This is how you can tell 
which window is active. 


| Important! | If you don’t see a change in the appearance of the CPU window, 
look at the way you entered the command. Did you enter CPU in uppercase 
letters? For this commana, it’s important that you enter the parameter in upper- 
case, as shown. 


Try This: 


Press the key to “cycle” through the windows in the display, 
making each one active in turn. Press as many times as necessary until 
the CPU window becomes the active window. 


Try This: 


You can also use the mouse to make a window active: 


1) Point to any location on the window’s border. 


2) Click the left mouse button. 


Be careful! If you point inside the window, the window becomes active when 
you press the mouse button, but something else may happen as well: 


_] If you’re pointing inside the CPU window, then the register you're pointing 
at becomes active. The debugger then treats the text you type as a new 
value for that register. Similarly, if you’re pointing inside the MEMORY 
window, the address you're pointing at becomes active. 


Press to get out of this. 


(_] If you’re pointing inside the DISASSEMBLY or FILE window, you'll set a 
breakpoint on the statement that you were pointing to. 


Point to the same statement; press the button again to delete the break- 
point. 


Resize the Active Window 


Resize the active window 


A 


UU 


This lesson shows you how to resize the active window. 


| Important! | Be sure the CPU window is still active. 


Make the CPU window as small as possible: 


size 4,3 


This tells the debugger to make the window 4 characters by 3 lines, which is 
the smallest a window can be. (If it were any smaller, the debugger wouldn't 
be able to display all four corners of the window.) If you try to enter smaller 
values, the debugger will warn you that you’ve entered an Invalid window size. 
The maximum width and length depend on which screen-size option you used 
when you invoked the debugger. 


Make the CPU window larger: 
size Enter the SIZE command without parameters 
C+] Make the window 3 lines longer 


Make the window 4 characters wider 


ESC Press this key when you finish sizing the window 


You can use @) to make the window shorter and © to make the window nar- 
rower. 


Try This: | You can use the mouse to resize the window (note that this process 
forces the selected window to become the active window). 


1) If you examine any window, you'll see a highlighted, backward “L” in the 
lower right corner. Point to the lower right corner of the CPU window. 


2) Press the left mouse button but don’t release it; move the mouse while 
you're holding in the button. This resizes the window. 


3) Release the mouse button when the window reaches the desired size. 
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Zoom the Active Window 


Zoom the active window 


Another way to resize the active window is to zoom it. Zooming the window 
makes it as large as possible. 


| Important! | The CPU window should still be active from the previous steps. 


E} Make the active window as large as possible: 


zoom 


The window should now be as large as possible, taking up the entire display 
(except for the menu bar) and hiding all the other windows. 


“Unzoom’ or return the window to its previous size by entering the ZOOM 
command again: 


zoom The ZOOM command will be recognized, 
even though the COMMAND window is hidden 
by the CPU window. 


The window should now be back to the size it was before zooming. 


S Try This: | You can use the mouse to zoom the window. 


Zoom the active window: 


KR 1) Point to the upper left corner of the active window. 


10 2) Click the left mouse button. 


Return the window to its previous size by repeating these steps. 
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Move the Active Window 


Move the active window 


UU 


This lesson shows you how to move the active window. 


| Important! | The CPU window should still be active from the previous steps. 


Move the CPU window to the upper left portion of the screen: 


move 0,1 The debugger doesn't let you move the window 
to the very top—that would hide the menu bar 


The MOVE command's first parameter identifies the window’s new X position 
on the screen. The second parameter identifies the window’s new Y position 
on the screen. The maximum X and Y positions depend on which screen-size 
option you used when you invoked the debugger and on the position of the win- 
dow before you tried to move it. 


Try This: | You canuse the MOVE commandwith no parameters and then use 
arrow keys to move the window: 


move 
Press G) until the CPU window is back where it was 
(it may seem as if only the border is moving—this is normal) 
ESC Press when you finish moving the window 


You can use @) to move the window up, G) to move the window down, and 
to move the window left. 


Try This: | You can use the mouse to move the window (note that this process 
forces the selected window to become the active window). 


1) Point to the top edge or left edge of the window border. 


2) Press the left mouse button, but don’t release the button; move the mouse 
while you're holding in the button. 


3) Release the mouse button when the window reaches the desired position. 
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Scroll Through a Window’s Contents 


Scroll through a window’s contents 


Many of the windows contain more information than can possibly be displayed 
at one time. You can view hidden information by moving through a window’s 
contents. The easiest way to do this is to use the mouse to scroll the display 
up or down. 


If you examine most windows, you'll see an up arrow near the top of the right 
border and a down arrow near the bottom of the right border. These are scroll 
arrows. 


Scroll through the contents of the DISASSEMBLY window: 


Point to the up or down scroll arrow. 


Press the left mouse button; continue pressing it until the dis- 
play has scrolled several lines. 


Release the button. 


Try This: 


window. 


You can use several of the keys to modify the display in the active 


Make the MEMORY window the active window: 

win MEMORY 

Now try pressing these keys; observe their effects on the window’s contents. 
e3) an) 


These keys don’t work the same for all windows; Section 13.5 (page 13-67) 
summarizes the functions of all the special keys and key sequences and how 
they affect different windows. 


Display the C Source Version of the Sample File / Execute Some Code 


Display the C source version of the sample file 
Now that you can find your way around the debugger interface, you can be- 


come familiar with some of the debugger’s more significant features. It’s time 
to load C code. 


Display the contents of a C source file: 


file sample.c 


This opens a FILE window that displays the contents of the file sample.c 
(sample.c was one of the files that contributed to making the sample object 
file). You can always tell which file you’re displaying by the label in the FILE 
window. Right now, the label should say FILE: sample.c. 


Execute some code 


Let’s run some code—not the whole program, just a portion of it. 


Execute a portion of the sample program: 


go main 


You've just executed your program up to the point where main() is declared. 
Notice how the display has changed: 


[| The current PC is highlighted in both the DISASSEMBLY and FILE 
windows. 


[|_| The addresses and object codes of the first several statements in the 
DISASSEMBLY window are highlighted because these statements are 
associated with the current C statement (which is highlighted in the FILE 
window). 


[_.] The CALLS window, which tracks functions as they’re called, now points 
to main(). 


[_] The values of the PC and TOS (and possibly some additional registers) 
are highlighted in the CPU window because they were changed by pro- 
gram execution. 
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Become Familiar With the Three Debugging Modes 


Become familiar with the three debugging modes 
The debugger has three basic debugging modes: 
|_| Mixed mode shows both disassembly and C at the same time. 


[_] Auto mode shows disassembly or C, depending on what part of your 
program happens to be running. 


[_} Assembly mode shows only the disassembly, no C, even if you’re 
executing C code. 


When you opened the FILE window in a previous step, the debugger switched 
to mixed mode; you should be in mixed mode now. (You can tell that you’re in 
mixed mode if both the FILE and DISASSEMBLY windows are displayed.) 


The following steps show you how to switch debugging modes. 


S Use the MoDe menu to select assembly mode: 


Look at the top of the display: the first line shows a row of pull- 
down menu selections. 


Point to the word MoDe on the menu bar. 


Press the left mouse button, but don’t release it; drag the 
mouse downward until Asm (the second entry) is highlighted. 


Release the button. 


This switches to assembly mode. You should see the DISASSEMBLY window, 
but not the FILE window. 


Switch to auto mode: 
1) Press [atr](p). This displays and freezes the MoDe menu. 


2) Now select C(auto). To do so, choose one of these methods: 


1 Press the arrow keys to move up/down through the menu; when 
C(auto) is highlighted, press (2). 


Type C. 


Point the mouse cursor at C(auto), then click the left mouse but- 
ton. 


Become Familiar With the Three Debugging Modes 


You should be in auto mode now, and you should see the FILE window but not 
the DISASSEMBLY window (because your program is in C code). Auto mode 
automatically switches between an assembly and a C display, depending on 
where you are in your program. Here’s a demonstration of that: 


Run to a point in your program that executes assembly language code: 


go meminit 


You're still in auto mode, but you should now see the DISASSEMBLY window. 
The current PC should be at the statement that defines the meminit label. 


Try This: 


You can also switch modes by typing one of these commands: 


asm __ switches to assembly-only mode 
c switches to auto mode 
mix switches to mixed mode 


Switch back to mixed mode before continuing: 


mix 


rlaliway Point 


You’ve finished the first half of the tutorial and the 
first set of lessons. 


If you want to close the debugger, just tyoe QUIT @). When you come back, 
reinvoke the debugger and load the sample program (page 3-3). Then turn 
to page 3-14 and continue with the second set of lessons. 
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Open Another Text File, Then Redisplay a C Source File / Use the Basic RUN Command 


Open another text file, then redisplay a C source file 


In addition to what you already know about the FILE window and the FILE 
command, you should also know that: 


[.} You can display any text file in the FILE window. 


[_] If you enter any command that requires the debugger to display a C source 
file, it automatically displays that code in the FILE window (regardless of 
whether the window is open or not and regardless of what is already 
displayed in the FILE window). 


Display a file that isn’t a C source file: 


file ..\autoexec.bat 


This replaces sample.c in the FILE window with your autoexec. 


Remember, you can tell which file you're displaying by the label in the FILE 
window. Right now, the label should say FILE: autoexec.bat. 


Redisplay another C source file (sample.c): 


func call 


Now the FILE window label should say FILE: sample.c because the call() func- 
tion is in sample.c. 


Use the basic RUN command 


The debugger provides you with several ways of running code, but it has one 
basic run command. 


Run your entire program: 


run 


Entered this way, the command basically means “run forever”. You may not 
have that much time! 


This isn’t very exciting; halt program execution: 


ESC 


Set Some Breakpoints 


Set some breakpoints 


When you halted execution in the previous step, you should have seen 
changes in the display similar to the changes you saw when you entered go 
main earlier in the tutorial. When you pressed , you had little control over 
where the program stopped. Knowing that information changed was nice, but 
what part of the program affected the information? 


This information would be much more useful if you picked an explicit stopping 
point before running the program. Then, when the information changed, you’d 
have a better understanding of what caused the changes. You can stop 
program execution in this way by setting software breakpoints. 


| Important! | This lesson assumes that you’re displaying the contents of 
sample.c in the FILE window. If you aren’t, enter: 


file sample.c 


Set a software breakpoint and run your program: 


1) Scroll to line 38 in the FILE window (the meminit() statement) and set 
a breakpoint at that line: 


* a) Point the mouse cursor at the statement on line 38. 


ib) Click the left mouse button. Notice how the line is highlighted; 


this identifies a breakpointed statement. 


Reset the program entry point: 


restart 


Enter the run command: 


run Program execution halts at the breakpoint 


Once again, you should see that some statements are highlighted in the CPU 
window, showing that they were changed by program execution. But this time, 
you know that the changes were caused by code from the beginning of the 
program to line 38 in the FILE window. 


Clear the breakpoint: 


m1) Point the mouse cursor at the statement on line 38. (It should still 
be highlighted from setting the breakpoint.) 


L 2) Click the left mouse button. The line is no longer highlighted. 
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Benchmark a Section of Code 


Benchmark a section of code 


You can use breakpoints to help you benchmark a section of code. This means 
that you'll ask the debugger to count the number of CPU clock cycles that are 
consumed by a certain portion of code. 


Benchmark some code: 


In sample.c (displayed in the FILE window), set two software break- 
points: one at line 38 (the meminit() statement) and one at line 65 (the 
xcall(value) statement). 


Reset the program entry point: 

restart 

Enter the run command: 

run This runs to the first breakpoint 
Enter the runb command: 


runb This runs to the second breakpoint 
(this may take several seconds) 


Now use the ? command to examine the contents of the CLK pseudo- 
register: 


2? clk (2) 


The debugger now shows a number in the display area; this is the number of 
CPU clock cycles consumed by the portion of code between the two break- 
pointed C statements. 


| Important! | The value in the CLK pseudoregister is valid only when you 


execute the RUNB command and when that execution is halted on break- 


pointed statements. 


Delete both software breakpoints: 


br The BR (breakpoint reset) command deletes 
all software breakpoints that were set 


Watch Some Values and Single-Step Through Code 


Watch some values and single-step through code 


Now you know how to update the display without running your entire program; 
you can set software breakpoints to obtain information at specific points in your 
program. But what if you want to update the display after each statement? No, 
you don’t have to set a breakpoint at every statement—you can use 
single-step execution. 


Set up for the single-step example: 


restart 
go main 


The debugger has another type of window called a WATCH window that’s very 
useful in combination with single-step execution. What’s a WATCH window 
for? Suppose you are interested in only a few specific register values, not all 
of the registers shown in the CPU window. Or suppose you are interested in 
a particular memory location or in the value of some variable. You can observe 
these data items in a WATCH window. 


Set up the WATCH window before you start the single-step execution. 


Open a WATCH window: 


wa arl, Stack Pointer 


wa pc 


wa *0x2059@prog, Call: 


wa i (2} 


You may have noticed that the WA (watch add) command can have one or two 
parameters. The first parameter is the item that you’re watching. The second 
parameter is an optional label. 


If the WATCH window isn’t wide enough to display the PC value, resize the 
window. 


lesson continues on the next page > 
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Watch Some Values and Single-Step Through Code 


Now try out the single-step commands. Hint: Watch the PC in the FILE and 
DISASSEMBLY windows; watch the value of i in the WATCH window. 


Single-step through the sample program: 


step 20 


Try This: | Notice that the step command single-stepped each assembly 


language statement (in fact, you single-stepped through 20 assembly 
language statements). Did you also notice that the FILE window displayed the 
source for the meminit() function when it was called? The debugger supports 
additional single-step commands that have a slightly different flavor. 
(_] For example, if you enter: 
cstep 20 
you'll single-step 20 C statements, not assembly language statements 
(notice how the PC “jumps” in the DISASSEMBLY window). 
[_] Reset the program entry point and run to main(). 


restart 
go main 


Now enter the NEXT command, as shown below. You'll be single-stepping 
20 assembly language statements, but the FILE window wont display the 
source for the meminit() function when meminit() is executed. 


next 20 
(There’s also a CNEXT command that “nexts” in terms of C statements.) 


Run Code Conditionally 


Run code conditionally 


Try executing this loop one more time. Take a look at this code; it’s doing a lot 
of work with a variable named i. You may want to check the value of i at specific 
points instead of after each statement. To do this, you set software breakpoints 
at the statements you’re interested in and then initiate a conditional run. 


First, clear out the WATCH window so that you won't be distracted by any 
superfluous data items. 


Delete the first three data items from the WATCH window (don’t watch 
them anymore): 


wd 3 
wd 1 
wd 1 


The variable i was the fourth item added to the WATCH window in the previous 
tutorial step, and it should now be the only remaining item in the window. 
Set up for the conditional run examples: 
Set software breakpoints at lines 39 and 41. 
Reset the program entry point: 


restart 


Run the first part of the program: 


go main 


Reset the value of i: 


?i=0 


Now initiate the conditional run: 


run i<10 


This causes the debugger to run through the loop as long as the value of i is 
less than 10. Each time the debugger encounters the breakpoints in the loop, 
it updates the value of i in the WATCH window. 


lesson continues on the next page > 
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Run Code Conditionally / WHATIS That? 


WHATIS that? 


3-20 


When the conditional run completes, close the WATCH window. 


Close the WATCH window: 


we [2] 


At some point, you might like to obtain some information about the types of 
data in your C program. Maybe things won’t be working quite the way you'd 
planned, and you'll find yourself saying something like “... but isn’t that sup- 
posed to point to an integer?” Here’s how you can check on this kind of infor- 
mation; be sure to watch the COMMAND window display area as you enter 
these commands. 


Use the WHATIS command to find the types of some of the variables de- 
clared in the sample program: 


whatis genum 
enum yyy genum; genum is an enumerated type 
whatis tiny6 
Struct tiny6 Is a structure 
slighe 
abiake 
sbiahe 
alialc 


alighe, ¥48 


Ip WalionyGe 
whatis call 
slike @eULIL ()) 8 call is a function that returns an integer 


whatis s 


short s; s is a short unsigned integer 
whatis zzz 
StrquGeeezizi Za 2zz Is a very long structure 
sliahe Jejills 
skighe lee 
Press to halt long listings 


Clear the COMMAND Window Display Area / Display the Contents of an Aggregate Data Type 


Clear the COMMAND window display area 


After displaying all of these types, you may want to clear them away. This is 
easy to do. 


Clear the COMMAND window display area: 


cls 

Try This: | CLs isn't the only system-type command that the debugger 
supports. 
cd .. Change back to the main directory 
dir Show a listing of the current directory 
ed c5xhll or cd sim5x Change back to the debugger directory 


Display the contents of an aggregate data type 


The WATCH window is convenient for watching single, or sca/ar, values. When 
you're debugging a C program, though, you may need to observe values that 
aren’t scalar; for example, you might need to observe the effects of program 
execution on an array. The debugger provides another type of window called 
a DISP window, where you can display the individual members of an array or 
structure. 


Show a structure in a DISP window: 
disp small 
Close the DISP window: 


Show another structure in a DISP window: 


disp bigl 


lesson continues on the next page > 
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Now you should see a display like the one below. The newly opened DISP 
window becomes the active window. Like the FILE window, you can always tell 
what’s being displayed because of the way the DISP window is labeled. Right 
now, it should say DISP: big1. 


Oxfff9 


(Note that the values displayed in this diagram may be different from what you 
see on the screen.) 


_.} Members b1, b2, b3, b4, and b5 are ints; you can tell because they’re 
displayed as integers (shown as plain numbers without prefixes). 


[_.} Member q1 is an array; you can tell because q1 shows [. . .] instead of a 
value. 


[.]} Member q2 is another structure; you can tell because q2 shows {. . .} 
instead of a value. 


[.} Member g3 is a pointer; you can tell because it is displayed as a hexadeci- 
mal address (indicated by a Ox prefix) instead of an integer value. 


If a member of a structure or an array is itself a structure or an array, or even 
a pointer, you can display its members (or the data it points to) in additional 
DISP windows (referred to as the original DISP window's children). 


Display what q3 is pointing to: 


< 1) Point at the address displayed next to the q3 label in big1’s 
display. 


tl 2) Click the left mouse button. 


This opens a second DISP window, named big1.q3, that shows what q3 is 
pointing to (it’s pointing to another structure). Close this DISP window, or move 
it out of the way. 


OM 


Display the Contents of an Aggregate Data Type 


Display array q1 in another DISP window: 


< 1) Point at the [. . .] displayed next to the q1 label in big1’s dis- 
play. 


i 2) Click the left mouse button. 


This opens another DISP window labeled DISP: big1.q1. 


| Important! | qi is actually a two-member array of structures. To view the two 
different structures, uSe (CONTROL) (PAGE DOWN) and (CONTROL) (PAGE UP). (Look at 
the name of this DISP window when you’re switching.) 


Try This: 


Display structure q2 in another DISP window. 


1) Close the additional DISP windows, or move them out of the way so that 


you can clearly see the original DISP window that you opened to display 
big1. 


2) Make big1’s DISP window the active window. 


3) Use these arrow keys to move the field cursor (_) through the list of big1’s 


members until the cursor points to q2. 


4) Now press (3). 


Close all of the DISP windows: 


1) Make big1’s DISP window the active window. 


2) Press (Fa). 


When you close the main DISP window, the debugger closes all of its children 
as well. 
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Display data in another format 
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Usually, when you add an item to the WATCH window or open a DISP window, 
the data is shown in its natural format. This means that ints are shown as 
integers, floats are shown as floating-point values, etc. Occasionally, you may 
wish to view data in a different format. This can be especially important if you 
want to show memory or register contents in another format. 


One way to display data in another format is through casting (which is part of 
the C language). In the expression below, the *(float *) portion of the expres- 
sion tells the debugger to treat address 0x800 as type float (exponential floa- 
ting-point format). 


Display memory contents in floating-point format: 


disp *(float *)0x800 


This opens a DISP window to show memory contents in an array format. The 
array member identifiers don’t necessarily correspond to actual addresses— 
they’re relative to the first address you request with the DISP command. In this 
case, the item displayed as item [0] is the contents of address 0x0800—it isn't 
memory location 0. Note that you can scroll through the memory displayed in 
the DISP window; item [1] is at Ox0801, and item [—1] is at OxOffe. 


You can also change display formats according to data type. This affects all 
data of a specific C data type. 


Change display formats according to data types by using the SETF (set 
format) command: 


1) Forcomparison, watch the following variables. Their C data types are 
listed on the right. 


wa i Type int 


wa f Type float 
wad Type double 


You can list all the data types and their current display formats: 


setf 


Display Data in Another Format 


Now display the following data types with new formats: 


setf int, c Ints as characters 
setf float, o Floats as octal integers 
setf double, x Doubles as hex integers 


List the data types to display formats again; note the changes in the 
display: 


setf 


Add the variables to the WATCH window again; use labels to identify 
the additions: 

wa i, MEWi 

wa f, NEWfL 

wa d, NEWd 


Notice the differences in the display formats between the first versions 
you added and these new versions. 


Now reset all data types back to their defaults: 


setf * 


A third way to display data in another format is to use the DISP, ?, MEM, or WA 
command with an optional parameter that identifies the new display format. 
The following examples are for ? and WA—DISP and MEM work similarly. 


Use display formats with the ? and WA commands: 
1) Evaluate a variable and display it as a character: 
? small.ra[1],c 


2) Add avariable to the watch window and display it as an octal integer: 


wa str.a,,o Notice that because no label was used 
with WA, an extra comma was inserted; 

otherwise, the o parameter would have 

been interpreted as a label. 


To get ready for the next step, close the DISP and WATCH windows. 
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Change some values 


You can edit the values displayed in the MEMORY, CPU, WATCH, and DISP 
windows. 


S Change a value in memory: 


1) Move or close the WATCH window if it’s obscuring the 
MEMORY window; then display memory beginning with ad- 
dress 0x0800: 


mem 0x800 
Point to the contents of memory location 0x0800. 


Click the left mouse button. Notice that this highlights and 
identifies the field to be edited. 


Type 0000. 


Press to enter the new value. 


Press to conclude editing. 


ke | = 
Try This: | Here’s another method for editing data that lets you edit a few more 


values at once. 


1) Make the CPU window the active window: 
win CPU 


MQ _ 2) Press the arrow keys until the field cursor (_ ) points to the PC contents. 
3) Press (3). 
4) Type 2000. 
Q) 5) Press @ enough times to point at the contents of register ARO. 
6) Type ffff. 
7) Press @ to enter the new value. 


ESC 8) Press to conclude editing. 
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Define a memory map 


You can set up a memory map to tell the debugger which areas of memory it 
can and can’t access. This is called memory mapping. When you invoked the 
debugger for this tutorial, the debugger automatically read a default memory 
map from the initialization batch file included in the c5xhil or sim5x directory. 
For the purposes of the sample program, that’s fine (which is why this lesson 
was saved for the end). 


View the default memory map settings: 


m1 [2] 


Look in the COMMAND window display area—you'll see a listing of the areas 
that are currently mapped. The ’C5x supports separate program and data 
spaces. Page 0 in the memory map is for program memory; page 1 is for data 
memory. 


It’s easy to add new ranges to the map or delete existing ranges. 


Change the memory map: 


1) Usethe MD (memory delete) command to delete the block of program 
memory: 


md 0x0, 0 


This deletes the block of memory beginning at address 0 in program 
memory. 


Use the MA (memory add) command to define a new block of program 
memory and a new block of data memory: 


ma 0x0,0,0x20, ROM 
ma 0x100,1,0x7£,RAM 
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Define your own command string 


If you find that you often enter a command with the same parameters, or often 
enter the same commands in sequence, you will find it helpful to have a short- 
hand method for entering these commands. The debugger provides an alias- 
ing feature that allows you to do this. 


This lesson shows you how you can define an alias to set up a memory map, 
defining the same map that was defined in the previous lesson. 


Define an alias for setting up the memory map: 


1) Usethe ALIAS commandto associate a nickname with the commands 
used for defining a memory map: 


alias mymap,”mr;ma 0x0,0,0x20, ROM; 
ma 0x100,1,0x7£,RAM;m1” 


(Note: Because of space constraints, the command is shown on two 
lines.) 


Now, to use this memory map, just enter the alias name: 
mymap 
This is equivalent to entering the following four commands: 


mr 
ma 0x0,0,0x20,ROM 
ma 0x100,1,0x7£,RAM 
ml 


Close the debugger 


This is the end of the tutorial—close the debugger. 


Close the debugger and return to the operating system: 


quit 
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Chapter 4 


The Debugger Display 


The ’C5x C source debugger has a window-oriented display. This chapter 
shows what windows can look like and describes the basic types of windows 


that you'll use. 


Topic Page 
4.1. Debugging Modes and Default Displays 4-2 
Auto mode 4-2 
Assembly mode 4-3 
Mixed mode 4-4 
Restrictions associated with debugging modes 4-4 
4.2 Descriptions of the Different Kinds of Windows 4-5 
and Their Contents 
COMMAND window 4-6 
DISASSEMBLY window 4-7 
FILE window 4-8 
CALLS window 4-9 
PROFILE window 4-11 
MEMORY windows 4-12 
CPU window 4-15 
DISP windows 4-16 
WATCH window 4-17 
4.3 Cursors 4-18 
4.4 The Active Window 4-19 
Identifying the active window 4-19 
Selecting the active window 4-20 
4.5 Manipulating Windows 4-21 
Resizing a window 4-21 
Zooming a window 4-23 
Moving a window 4-24 
4.6 Manipulating a Window’s Contents 4-26 
Scrolling through a window’s contents 4-26 
Editing the data displayed in windows 4-28 
4.7 Closing a Window 4-29 
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4.1 Debugging Modes and Default Displays 


Auto mode 


The debugger has three debugging modes: 


[_} Auto mode 
[} Assembly mode 
__J Mixed mode 


Each mode changes the debugger display by adding or hiding specific win- 
dows. Some windows, such as the COMMAND window, may be present in all 
modes. The following figures show the default displays for these modes and 
show the windows that the debugger automatically displays for these modes. 
These modes cannot be used within the profiling environment; only the 
COMMAND, PROFILE, DISASSEMBLY, and FILE windows are available. 


In auto mode, the debugger automatically displays whatever type of code is 
currently running—assembly language or C. This is the default mode; when 
you first invoke the debugger, you'll see a a display similar to Figure 4—1. Auto 
mode has two types of displays: 


(_] When the debugger is running assembly language code, you'll see an 
assembly display similar to the one in Figure 4-1. The DISASSEMBLY 
window displays the reverse assembly of memory contents. 


Figure 4—1. Typical Assembly Display (for Auto Mode and Assembly Mode) 


Load Break Watch Memory Color MoDe Analyis Pin Step=F8 Next=F10 


-—DISASSEMBLY 
20cf b£08 c_into: ARO, #08alh 0000005£ 
20d1 b£09 AR1, #00a1h O1ff01£f 
2043 b£00 0 00000005 
20d4 be47 SxM 20cf 
20d5 b£80 #2143h 08ab 
20d7 b801 #1 08a5 
20d8 e388 20dch, EQ 00a4 
20da_ 7a89 20e0h, *, ARL 08a4 
20de 7a89 main, *,AR1 2610 
20de 7a89 abort, *, AR1L 0038 
20e0 b£80 #2143h O1ff 

8bc00 #0 0000 
a680 * 08ab 
b801 #1 ffel 
028a AR2,*,AR2 0800 


‘MEMORY 
TMS320C5x Revision 1 0000 0000 


0008 0000 
Loading sample.out 0010 O8ab 

34 Symbols loaded 0018 O8ab 
Done 0020 


>>>[] 0028 
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(_} When the debugger is running C code, you'll see a C display similar to the 
one in Figure 4—2. (This assumes that the debugger can find your C 
source file to display in the FILE window. If the debugger can’t find your 
source, then it switches to mixed mode.) 


Figure 4—2. Typical C Display (for Auto Mode Only) 


Assembly mode 


Load Break Watch Memory Color Analysis Pin Run=F5 Step=F8 Next=F10 


FILE: sample.c 

00042 double d; 

00043 int ai[10]; 
00044 int aai[10] [5]; 
00045 char ac[10]; 
00046 int Api; 

00047 char =xpCy) 

00048 

00049 extern call(); 


00059 exter meminit (); 
00060 
00061 main() 


00062 { 
00063 int i = 0; 

00064 int j = 0; 

00065 meminit () ; 

COMMAND | --CALLS 
TMS320C5x Debugger A 1: main() 


Copyright (c) 1990, 1992 
TMS320C5x Revision 1 
file sample.c 


go main v 


E : 


When you're running assembly language code, the debugger automatically 
displays windows as described for assembly mode. 


When you’re running C code, the debugger automatically displays the 
COMMAND, CALLS, and FILE windows. If you want, you can also open a 
WATCH window and DISP windows. 


Assembly mode is for viewing assembly language programs only. In this 
mode, you'll see a display similar to the one shown in Figure 4—1. When you’re 
in assembly mode, you'll always see the assembly display, regardless of 
whether C or assembly language is currently running. 


Windows that are automatically displayed in assembly mode include the 
MEMORY window, the DISASSEMBLY window, the CPU register window, and 
the COMMAND window. If you choose, you can also open a WATCH window 
in assembly mode. 
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Mixed mode 


Mixed mode is for viewing assembly language and C code at the same time. 
Figure 4—3 shows the default display for mixed mode. 


Figure 4—3. Typical Mixed Display (for Mixed Mode Only) 


Load Break Watch Memory Color Analysis Pin Run=F5 Step=F8 =m 
-—DISASSEMBLY- 1 CPU: 1 
0040 Oaa0 main: POPD ++ Ajacc 00000002 A 
0041 80a0 SAR ARO, *+ ACCB ffffffff 
0042 8180 SAR AR1,* PREG 00000000 
PC 0107 
0043 b004 LAR ARO, #4 TOS £050 
0044 00ea LAR ARO, *0+,AR2 ARO 0000 
0045 b900 ZAC AR1 o95£ 
0046 b201 LAR AR2, #1 AR2 dffd 
0047  8be0d MAR *O+ WiaAR3 ffff 
AR4 £080 
0048 90a0 SACL oP _| ARS 09c6 v 
-—FILE: sample.c jl AR6 bffft 
00046 int Api; A|AR7 bftt 
00047 char *xpc; CALLS 
00048 1: main() 
00049 extern call(); 
00059 exter meminit (); 
00060 v 
00061 main() _| el 


‘MEMORY 
0000 0007 0007 0007 0007 bfftt ££00 0000 


0007 0008 0000 bfftt 0000 0000 0001 0001 
000e 0001 bftt 0000 Oo9f5 dffd ffff £080 
0015 09c6 bfff bfff £7££ 0000 bfff bffft | 


‘COMMAND 
file sample.c 


go main 


OQOlc bffft bftt eli) bff£f 0000 0000 0900 


In mixed mode, the debugger displays all windows that can be displayed in 
auto and assembly modes—regardless of whether you’re currently running 
assembly language or C code. This is useful for finding bugs in C programs 
that exploit specific architectural features of the ’C5x. 


Restrictions associated with debugging modes 
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The assembly language code that the debugger shows you is the disassembly 
(reverse assembly) of the memory contents. If you load object code into 
memory, then the assembly language code is the disassembly of that object 
code. If you don’tload an object file, then the disassembly won’tbe very useful. 


Some commands are valid only in certain modes, especially if a command 
applies to a window that is visible only in certain modes. In this case, entering 
the command causes the debugger to switch to the mode that is appropriate 
for the command. This applies to these commands: 


dasm 
calls 


func 
file 


mem 
disp 
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4.2 Descriptions of the Different Kinds of Windows and Their Contents 


The debugger can show several types of windows. This section lists the 
various types of windows and describes their characteristics. 


Every window is identified by a name in its upper left corner. Each type of 
window serves a specific purpose and has unique characteristics. There are 
nine different windows, divided into four general categories: 


(_} The COMMAND window provides an area for typing in commands and 
for displaying various types of information such as progress messages, 
error messages, or command output. 


(_} Code-display windows are for displaying assembly language or C code. 
There are three code-display windows: 


HM The DISASSEMBLY window displays the disassembly (assembly 
language version) of memory contents. 

HM The FILE window displays any text file that you want to display; its 
main purpose, however, is to display C source code. 


M@ The CALLS window identifies the current function traceback (when C 
code is running). 


[| The PROFILE window displays statistics about code execution. This 
window is available only when you are in the profiling environment. 


[_] Data-display windows are for observing and modifying various types of 
data. There are four data-display windows: 


mM AMEMORY window displays the contents of a range of memory. You 
can display up to four MEMORY windows at one time. 


HM The CPU window displays the contents of ’C5x registers. 


H@ ADISP window displays the contents of an aggregate type such as an 
array or structure, showing the values of the individual members. You 
can display up to 120 DISP windows at one time. 


H@ The WATCH window displays selected data such as variables, specif- 
ic registers, or memory locations. 


You can move or resize any of these windows; you can also edit any value in 
a data-display window. Before you can perform any of these actions, however, 
you must select the window you want to move, resize, or edit and make it the 
active window. For more information about making a window active, see 
Section 4.4, The Active Window, on page 4-19. 


The remainder of this section describes the individual windows. 
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COMMAND window 
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COMMAND 


p- 


display pyright (c) 1990,1992 
area TMS320C5x Revision 1 
Loading sample.out 
Done 
le sample.c Vv 
Soa ae 5 alr | 
Ee aa 
command line 
cursor sy 
Purpose [_.] Provides an area for entering commands 
[_.] Provides an area for echoing commands and displaying 
command output, errors, and messages 
Editable? Command line is editable; command output isn’t 
Modes All modes 
Created Automatically 


Affected by [_] All commands entered on the command line 
[_] All commands that display output in the display area 
(J Any input that creates an error 


The COMMAND window has two parts: 


[_} Command line. This is where you enter commands. When you want to 
enter a command, just type—no matter which window is active. The 
debugger keeps a list of the last 50 commands that you entered. You can 
select and re-enter commands from the list without retyping them. (For 
more information on using the command history, see Using the command 
history, page 5-5.) 


(_] Display area. This area of the COMMAND window echoes the command 
that you entered, shows any output from the command, and displays 
debugger messages. 


For more information about the COMMAND window and entering commands, 
refer to Chapter 5, Entering and Using Commands. 
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DISASSEMBLY window 
; disassembly 
memory object (assembly language 
address code constructed from object code) 
-—DISASSEMB: 1 
0106 ef00 RET 4 
0107 b£08 c_into: LAR ARO, #095fh current PC 
0109 b£09 LAR AR1, #095fh 
010b b£00 SPM 0 
010d b£80 LACC #017ch 
010£ b£01 ADD #1 
0110 e388 BCND 0114h, EQ 
0112 7a89 CALL 0118h v 
0114 7a89 CALL main _| 
» 
Purpose Displays the disassembly (or reverse assembly) of memory 
contents 
Editable? No; pressing the edit key (2)) or the left mouse button sets 
a software breakpoint on an assembly language statement 
Modes Auto (assembly display only), assembly, and mixed 
Created Automatically 
Affected by [_.}| DASM and ADDR commands 


[]} Breakpoint and run commands 


Within the DISASSEMBLY window, the debugger highlights: 


[_] The statement thatthe PC is pointing to (if that line is in the current display) 
[_| Any statements with software breakpoints 
[| The address and object code fields for all statements associated with the 


current C statement, as shown below 


a 


ae 
These assembly 
language statements 


DISASSEMBLY- 1 > 
0040 OaaOd main: A 
0041 80a0 | 
0042 8180 
0043 bo004 
are associated with ——r1uz: t1.c 
this C statement | 00049 extern call(); current PC 
ee meminit () ; 
00061 main() 
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FILE window 


text 
file 


-—FILE: sample.c 


0001 struct xxx 
00002 

00003 union 
00004 struct zzz 
00005 

00006 struct 
00007 enum 


uuu 


YYY, 


aa 


“ 


Sle fiplenteye sure, sel f ele Sivie Gerd ce PG sh eyableiel score 

Str, astro, 
aint ul,) a2, us, U4, u5)[6l); struct xxx U6; } 

int b1,b2,be,b4,b5; struct xxx ql[2],q2; str 
bigl, *big2, big3[6]; 


aastr[ 


antes, v7, 2,7 ince spter- tloat *fptr;ichar sral|S Vv 
RED, GREEN, BLUE } genum, *penum, aenum[5] [4] | 


Purpose 


Editable? 


Modes 
Created 


Affected by 


You can use the FILE command to display the contents of any file within the 
FILE window, but this window is especially useful for viewing C source files. 
Whenever you single-step a program or run a program and halt execution, the 
FILE window automatically displays the C source associated with the current 
point in your program. This overwrites any other file that may have been 


Shows any text file you want to display 


No; if the FILE window displays C code, pressing the edit key 
(C3) ) or the left mouse button sets a software breakpoint on 
a C statement 


Auto (C display only) and mixed 


LJ 


L} 
LL} 
L} 


displayed in the window. 


With the FILE command 
Automatically when you’re in auto or mixed mode and 
your program begins executing C code 


FILE, FUNC, and ADDR commands 
Breakpoint and run commands 


Within the FILE window, the debugger highlights: 


[_] The statementthat the PC is pointing to (if that line is in the current display) 
[_] Any statements where you’ve set a software breakpoint 


CALLS window 
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--CALLS 
order of functions called ~~ [Eee 

Zee Cael (i) 
abe in () 


names of functions called 


current function 
is at top of list 


Purpose Lists the function you're in, its caller, and its caller, etc., as 
long as each function is a C function 

Editable? No; pressing the edit key (@2)) or the left mouse button 
changes the FILE display to show the source associated with 
the called function 

Modes Auto (C display only) and mixed 

Created [_} Automatically when you're displaying C code 
[_| With the CALLS command if you closed the window 

Affected by Run and single-step commands 


The display in the CALLS window changes automatically to reflect the latest 


function call. 


a 


If you haven’t run any code, then no func- 
tions have been called yet. You'll also see 
this if you’re running code but are not 
currently running a C function. 


In C programs, the first C function is main. 


As your program runs, the contents of 
the CALLS window change to reflect 
the current routine that you’re in and 

where the routine was called from. 
When you exit a routine, its name is 
popped from the CALLS list. 


CALLS > 


—CALLS 
2: xcall() 


1: main() 


—CALLS 


The Debugger Display 4-9 


Descriptions of the Different Kinds of Windows and Their Contents 


4-10 


If a function name is listed in the CALLS window, you can easily display the 
function in the FILE window: 


1) Point the mouse cursor at the appropriate function name that is listed in 
the CALLS window. 


2) Click the left mouse button. This displays the selected function in the FILE 
window. 


1) Make the CALLS window the active window (see Section 4.4, The Active 
Window, page 4-19). 


2) Use the arrow keys to move up/down through the list of function names 
until the appropriate function is indicated. 


3) Press (3). This displays the selected function in the FILE window. 


You can close and reopen the CALLS window. 


[_] Closing the window is a two-step process: 
1) Make the CALLS window the active window. 
2) Press (4). 


(_} To reopen the CALLS window after you've closed it, enter the CALLS 
command. The format for this command is: 


calls 
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PROFILE window 
profile data 
PROFILE 
Area Name Count Inclusive Incl-Max Exclusive Excl-Max 4 
AR 00£00001-00£00008 1 65 65 19 19 
profile CL <sample>#58 1 50 50 7 Yu 
areas CR <sample>#59-64 ak 87 87 44 44 
CF call() 24 1623 99 1089 SSI 
AL meminit 1 3 3 3 3 V 
AL 00£00059 disabled | 
Purpose Displays statistics collected during a profiling session 
Editable? No 
Modes Auto 
Created By invoking the debugger with the —profile option 
Affected by [| The PF and PQ commands 


[| Any commands on the View menu 
[_] Clicking in the header area of the window 


The PROFILE window is visible only when you are in the profiling environment. 
The illustration above shows the window with a default set of data, but the 
display can be modified to show specific sets of data collected during a profil- 
ing session. 


Note that within the profiling environment, the only other available windows are 
the COMMAND window, the DISASSEMBLY window, and the FILE window. 


For more information about the PROFILING window (and about profiling in 
general), refer to Chapter 12, Profiling Code Execution. 
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MEMORY windows 
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0000 
0007 
addresses ne 
001lc 
0023 
Purpose Displays the contents of memory 
Editable? Yes—you can edit the data (but not the addresses) 
Modes Auto (assembly display only), assembly, and mixed 
Created [_] Automatically (the default MEMORY window only) 
J With the MEM# commands (up to three additional 
MEMORY windows) 


Affected by MEM commands: MEM, MEM1, MEM2, and MEM3 


The MEMORY window has two parts: 


(_} Addresses. The first column of numbers identifies the addresses of the 
first column of displayed data. No matter how many columns of data you 
display, only one address column is displayed. Each address in this 
column identifies the address of the data immediately to its right. 


(_] Data. The remaining columns display the values at the listed addresses. 
You can display more data by making the window wider and/or longer. 


The MEMORY window above has seven columns of data, so each new 
address is incremented by seven. Although the window shows seven col- 
umns of data, there is still only one column of addresses; the first value is at 
address 0x0000, the second at address 0x0001, etc.; the eighth value 
(first value in the second row) is at address 0x0007, the ninth at address 
0x0008, etc. 


As you run programs, some memory values change as the result of program 
execution. The debugger highlights the changed values. Depending on how 
you configure memory for your application, some locations may be invalid/ 
unconfigured. The debugger also highlights these locations (by default, it 
shows these locations in red). 


Descriptions of the Different Kinds of Windows and Their Contents 


Three additional MEMORY windows called MEMORY1, MEMORY2, and 
MEMORY? are available. The default MEMORY window does not have an ex- 
tension number in its name; this is because MEMORY1, MEMORY2, and 
MEMORYS3 are optional windows and can be opened and closed throughout 
your debugging session. Having four windows allows you to view four different 


memory ranges. Refer to Figure 4—4. 


Figure 4-4. The Default and Additional MEMORY Windows 


[—MEMORY3 [PROG] The default 
0800 0000 0000 e3d6 c9fd 83a7 8544 Oeaa 0004 A MEMORY 
b2a7 window 


0808 e5de dbf6 bd9d 2579 30c3 0000 a149 
[—MEMORY2 

0810] 1000 6d8£ £69a dbd3 £ff6 5a07 Oab3 

0818| 1008 ££f7 6d9b Ocfd d4db 2a0b 8c90 e909 6e12 
of SMEMORYL_ [PROG] 

0820/ 1010 20ce b£08 08al b£09 O08al bf00 be47 bEBO 2147 A 

0828) 1018 2047 b801 e388 20dc 7a89 20e0 7a89 2000 7a99 

MEMORY 
1020 20d£| 0000 0000 0000 0000 0000 o1f£ ££00 oops 0038 


1028 20e7| 0008 0000 0000 20f1 20f3 0001 £ffel £f£ff1 0000 
00a7 


31d4 5018 A 


20ef) 0010 O8ab O8ac O08a5 O00a3 0004 0807 08a4 
20£7) 0018 O8ab O8ab 0000 0000 0000 0000 ££77 5555 
0020 0000 0000 0000 0000 249d ££££ 0000 0000 
0028 ffff fLff OOOf 0000 0000 0000 0000 0000 


Additional 
MEMORY windows 


To create an additional MEMORY window or to display another range of 
memory in the current window, use the MEM command. 


(_] Creating a new MEMORY window. 


If the default MEMORY window is the only MEMORY window open and 
you want to open another MEMORY window, enter the MEM command 


with the appropriate extension number: 

mem[#] address 

For example, if you want to create a new memory window starting at ad- 
dress 0x8000, you would enter: 

mem1 0x8000 


This displays a new window, MEMORY1, showing the contents of memory 
starting at the address 0x8000. 


The 'C5x has separate data, program, and I/O spaces. By default, the 
MEMORY window shows data memory. If you want to display program 
memory, you can enter the MEM command like this: 


mem[#] address@prog 
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The @prog suffix identifies the address as a program memory address. 
You can also use @data to display data memory. However, if you are dis- 
playing data memory, the @data is unnecessary because data memory is 
the default. If you are using an emulator or EVM, you can display I/O space 
by using @io. 

When you display program memory, the MEMORY window’s label 
changes to remind you that you are no longer displaying data memory: 


MEMORY [PROG] 
0000 ££80 1000 0000 0000 0000 0000 0000 


0007. 0000 0000 0000 0000 0000 0000 0000 

The MEMORY label |oo0e 0000 0000 0000 0000 0000 0000 0000 
changes tO |o015 0000 0000 0000 0000 0000 0000 0000 
MEMORY [PROG] _ }oo1c fefa fdcef 7175 1454 57d3 5555 ££ff 


d 


(_] Displaying a new memory range in the current MEMORY window. 


Displaying another block of memory identifies a new starting address for 
the memory range shown in the current MEMORY window. The debugger 
displays the contents of memory at address in the first data position in your 
MEMORY window. The end of the range is defined by the size of the win- 
dow. 


If the only MEMORY window open is the default MEMORY window, you 
can view different memory locations by entering: 


mem_ address 


To view different memory locations in the optional MEMORY windows, use 
the MEM command with the appropriate extension number on the end. For 


example: 
To do this. . . Enter this. . . 
View the block of memory starting at address mem1 0x8000 


0x8000 in the MEMORY1 window 


View another block of memory starting ataddress mem2 0x002f 
0x002f in the MEMORY2 window 


TT | 
Note: 


If you want to view a different block of memory explicitly in the default 
MEMORY window, you can use the aliased command MEMO. This works 
exactly the same as the MEM command. To use this command, enter: 


mem0 address 
ppp I“ I ssI‘_§|SSINBNSISI 


CPU window 


Descriptions of the Different Kinds of Windows and Their Contents 


You can close and reopen additional MEMORY windows as often as you like. 
(_} Closing an additional MEMORY window. 
Closing a window is a two-step process: 


1) Make the appropriate MEMORY window the active window (see Sec- 
tion 4.4 on page 4-19). 


2) Press (4). 
Remember, you cannot close the default MEMORY window. 
[_} Reopening an additional MEMORY window. 


To reopen an additional MEMORY window after you've closed it, enter the 
MEM command with its appropriate extension number. 


cpu 
: acc 00000002 4 
registeL-—raccs rerecere 
name PREG 00000000 
PC 0107 
TOS £050 
ARO 0000 
AR1L 095£ 
AR2  dffd 
AR3 f£f£ 
AR4 £080 


AR5 09c6 
£££ 
registe. ART bfff 


STO  8e00 
contents Be as 


PMST 0008 v 
TIM f£4d 
IFR 0000 
CPU 
Acc 00000002 ACCB f£f£fffLfFL PREG 00000000 
The display PC 0107 TOS £050 ARO 0000 ARI O9fb 
changes when you AR2 dffd AR3 ffff AR4 £080 AR5 09e6 
resize the window AR6 bfff ART bfff STO 8e00 ST1 8ffc 
Purpose Shows the contents of the ’C5x registers 
Editable? Yes—you can edit the value of any displayed register 
Modes Auto (assembly display only), assembly, and mixed 
Created Automatically 


Affected by Data-management commands 


As you run programs, some values displayed in the CPU window change as 
the result of program execution. The debugger highlights changed values. 
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--DISP: str -——__________—__, 
a 84 4 

b 86 
structure —-+2 172 


members a DISP: str.£4 ———____, 
£27 7 [0] 44276127 A 
Vv [1] 1778712578 
£3  0x18740001 
member FA fleaat | [2] 555492660 


values [3] 356713217 
ee 138412802 
[5] 182452229 
[6] 35659888 
This member is an array, and [7] 37749506 
you can display its contents in [8] 134742016 \ 
a second DISP window [9] 138412801 _| 


Purpose Displays the members of a selected structure, array, or 
pointer, and the value of each member 

Editable? Yes—you can edit individual values 

Modes Auto (C display only) and mixed 

Created With the DISP command 


Affected by DISP command 


A DISP window is similar to a WATCH window, but it shows the values of an 
entire array or structure instead of a single value. Use the DISP command to 
open a DISP window; the basic syntax is: 


disp expression 
Data is displayed in its natural format: 


[_] Integer values are displayed in decimal. 

|_| Floating-point values are displayed in floating-point format. 

[|_| Pointers are displayed as hexadecimal addresses (with a Ox prefix). 
[_] Enumerated types are displayed symbolically. 


If any of the displayed members are arrays, structures, or pointers, you can 
bring up additional DISP windows to display their contents—up to 120 DISP 
windows can be open at once. 


WATCH window 


Descriptions of the Different Kinds of Windows and Their Contents 


watch index—_—_____[_1:__ aro.-—C—soo'x1802 
PAs X+X 4 


Shs uf | 


label current value 


<P 


Purpose Displays the values of selected expressions 

Editable? Yes—you can edit the value of any expression whose value 
corresponds to a single storage location (in registers or 
memory). In the window above, for example, you could edit 
the value of PC but couldn’t edit the value of X+X. 

Modes Auto, assembly, and mixed 

Created With the WA command 

Affected by WA, WD, and WR commands 


The WATCH window helps you to track the values of arbitrary expressions, 
variables, and registers. Use the WA command for this; the syntax is: 


wa_ expression |, label] 


WA adds expression to the WATCH window. (If there’s no WATCH window, 
then WA also opens a WATCH window). 


To delete individual entries from the WATCH window, use the WD command. 
To delete all entries at once and close the WATCH window, use the WR 
command. 


Although the CPU window displays register contents, you may not be 
interested in the values of all these registers. In this situation, it is convenient 
to use the WATCH window to track the values of the specific registers you’re 
interested in. 
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4.3 Cursors 


The debugger display has three types of cursors: 


[_] The command-line cursor is a block-shaped cursor that identifies the 
current character position on the command line. Arrow keys do not affect 
the position of this cursor. 


( COMMAND: 
Copyright (c) 1990,1992 


TMS320C5x Revision 1 


p- 


Loading sample.out 
Done 


file sample.c 


v 
>>> go main | 
— command line cursor 


(_} The mouse cursor is a block-shaped cursor that tracks mouse move- 
ments over the entire display. This cursor is controlled by the mouse driver 
installed on your system; if you haven't installed a mouse, you won’t see 
a mouse cursor on the debugger display. 


(_] The current-field cursor identifies the current field in the active window. 
On PCs, this is the hardware cursor that is associated with your graphics 
card. Arrow keys do affect this cursor’s movement. 


a 


CPU 1 
Acc 00000002 ACCB ffffffff PREG 00000000 A 


PC 0107 TOS £050 ARO 0000 AR1 O9fb 
AR2 dffd AR3 ffff AR4 £080 AR5 O09e6 
AR6 bfff AR7 bfff STO 8e00 ST1 8ffc 


current field cursor 


The Active Window 


4.4 The Active Window 


The windows in the debugger display aren’t fixed in their position or in their 
size. You can resize them, move them around, and, in some cases, close 
them. The window that you’re going to move, resize, or close must be active. 


You can move, resize, zoom, or close only one window at a time; thus, only one 
window at atime can be the active window. Whether or not a window is active 
doesn’t affect the debugger’s ability to update information in a window—it 
affects only your ability to manipulate a window. 


Identifying the active window 


The debugger highlights the active window. When windows overlap on your 
display, the debugger pops the active window to be on top of other windows. 


You can alter the active window’s border style and colors if you wish; 
Figure 4—5 illustrates the default appearance of an active window and an 
inactive window. 


Figure 4—5. Default Appearance of an Active and an Inactive Window 


An active window (default appearance) 
‘COMMAND 


TMS320C5x Debugger 
Copyright (c) 1990, 1992 


This window is TMS320C5x Revision 1 
highlighted to show __||#°ading sample. out 
that itis active — ||??? 


An inactive window (default appearance) 


COMMAND 1 
TMS320C5x Revision 1 


Loading sample.out 

Done 

This window is not | file sample.c 

highlighted and is | go main v 


not active | >>> | 


Note: Onmonochrome monitors, the border and selection corner are highlighted as shown in 
the illustration. On color monitors, the border and selection corner are highlighted as 
shown in the illustration, but they also change color (by default, they change from white to 
yellow when the window becomes active). 


The Debugger Display 4-19 


The Active Window 


Selecting the active window 
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Va 


win 


You can use one of several methods for selecting the active window: 


1) Pointto any location within the boundaries or on any border of the desired 
window. 


2) Click the left mouse button. 


Note that if you point within the window, you might also select the current field. 
For example: 


_} If you point inside the CPU window, then the register you're pointing at 
becomes active, and the debugger treats any text that you type as a new 
register value. If you point inside the MEMORY window, then the address 
value you’re pointing at becomes active and the debugger treats any text 
that you type as anew memory value. 


Press to get out of this. 


_] If you point inside the DISASSEMBLY or FILE window, you'll set a break- 
point on the statement you’re pointing to. 


Press the button again to clear the breakpoint. 


This key cycles through the windows on your display, making each one active 
in turn and making the previously active window inactive. Pressing this key 
highlights one of the windows, showing you that the window is active. Pressing 
again makes a different window active. Press as many times as nec- 
essary until the desired window becomes the active window. 


The WIN command allows you to select the active window by name. The 
format of this command is: 


win WINDOW NAME 


Note that the WINDOW NAME is in uppercase (matching the name exactly as 
displayed). You can spell out the entire window name, but you really need to 
specify only enough letters to identify the window. 


or 


The Active Window / Manipulating Windows 


For example, to select the DISASSEMBLY window as the active window, you 
can enter either of these two commands: 


win DISASSEMBLY 
win DISA 


If several windows of the same type are visible on the screen, don’t use the 
WIN command to select one of them. 


If you supply an ambiguous name (such as C, which could stand for CPU or 
CALLS), the debugger selects the first window it finds whose name matches 
the name you supplied. If the debugger doesn’t find the window you asked for 
(because you closed the window or misspelled the name), then the WIN 
command has no effect. 


4.5 Manipulating Windows 


Resizing a window 


Awindow’s size and its position in the debugger display aren’t fixed—you can 
resize and move windows. 


Note: 


You can resize or move any window, but first the window must be active. For 
information about selecting the active window, see Section 4.4 (page 4-19). 


| ss) 


The minimum window size is three lines by four characters. The maximum 
window size varies, depending on which screen size option you’re using, but 
you can’t make a window larger than the screen. 


There are two basic ways to resize a window: 


[__} By using the mouse 
(_] By using the SIZE command 
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1) Point to the lower right corner of the window. This corner is highlighted— 
here’s what it looks like: 


‘COl 

TMS320C5x Debugger 
Copyright (c) 1990, 1992 
TMS320C5x Revision 1 


Loading sample.out 


Dene lower right corner 
ss ae (highlighted) 


2) Grab the highlighted corner by pressing one of the mouse buttons; while 
pressing the button, move the mouse in any direction. This resizes the 
window. 


3) Release the mouse button when the window reaches the desired size. 


The SIZE command allows you to size the active window. The format of this 
command is: 


size [width, length | 
You can use the SIZE command in one of two ways: 
Method 1 Supply a specific width and length. 


Method 2 Omit the width and length parameters and use arrow keys to 
interactively resize the window. 


SIZE, method 1: Use the width and length parameters. Valid values for the 
width and length depend on the screen size and the window position on the 
screen. If the window is in the upper left corner of the screen, the maximum 
size of the window is the same as the screen size minus one line. (The extra 
line is needed for the menu bar.) For example, if the screen size is 80 charac- 
ters by 25 lines, the largest window size is 80 characters by 24 lines. 


If a window is in the middle of the display, you can’t size it to the maximum 
height and width—you can size it only to the right and bottom screen borders. 
The easiest way to make a window as large as possible is to zoom it, as 
described on page 4-23. 


For example, if you want to use commands to make the CALLS window 8 
characters wide by 20 lines long, you could enter: 


win CALLS 
size 8, 20 


Zooming a window 


a 


Manipulating Windows 


SIZE, method 2: Use arrow keys to interactively resize the window. If you 
enter the SIZE command without width and /ength parameters, you can use 
arrow keys to size the window: 


© Makes the active window one line longer. 

as) Makes the active window one line shorter. 

Makes the active window one character narrower. 
Makes the active window one character wider. 


When you're finished using the cursor keys, you must press or ; 


For example, if you want to make the CPU window three lines longer and two 
characters narrower, you can enter: 
win CPU 


size 
eames es) Oo (ESC) 


Another way to resize the active window is to zoom it. Zooming a window 
makes it as large as possible, so that it takes up the entire display (except for 
the menu bar) and hides all the other windows. Unlike the SIZE command, 
zooming is not affected by the window’s position in the display. 


To “unzoom” a window, repeat the same steps you used to zoom it. This will 
return the window to its prezoom size and position. 


There are two basic ways to zoom or unzoom a window: 


[_} By using the mouse 
|_| By using the ZOOM command 


1) Point to the upper left corner of the window. This corner is highlighted— 
here’s what it looks like: 


‘CO! 
- a Copyright (c) 1990, 1992 
upper left corner TMS320C5x Revision 1 


(highlig hted) Loading sample.out 


2) Click the left mouse button. 
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Al) 


U0 


move 


You can also use the ZOOM command to zoom/unzoom the window. The 
format for this command is: 


zoom 


The windows in the debugger display don’t have fixed positions—you can 
move them around. 


There are two ways to move a window: 


__] By using the mouse 
__] By using the MOVE command 


1) Point to the left or top edge of the window. 


‘COl 
Copyright (c) 1990, 1992 
TMS320C5x Revision 1 


Point to the top edge 
or the left edge 


Loading sample.out 


2) Press the left mouse button, but don’t release it; now move the mouse in 
any direction. 


3) Release the mouse button when the window is in the desired position. 


The MOVE command allows you to move the active window. The format of this 
command is: 


move _ [X position, Y position [, width, length ] | 
You can use the MOVE command in one of two ways: 
Method 1 Supply a specific X position and Y position. 


Method 2 Omit the X position and Y position parameters and use arrow 
keys to interactively resize the window. 


Manipulating Windows 


MOVE, method 1: Use the X position and Y position parameters. You can 
move a window by defining a new XY position for the window’s upper left cor- 
ner. Valid X and Y positions depend on the screen size and the window size. 
X positions are valid if the X position plus the window width in characters is less 
than or equal to the screen width in characters. Y positions are valid if the Y 
position plus the window height is less than or equal to the screen height in 
lines. 


For example, if the window is 10 characters wide and 5 lines high and the 
screen size is 80 x 25, the command move 70, 20 would put the lower right- 
hand corner of the window in the lower right-hand corner of the screen. No X 
value greater than 70 or Y value greater than 20 would be valid in this example. 


TS, | 
Note: 


If you choose, you can resize a window at the same time you move it. To do 
this, use the width and length parameters in the same way that they are used 


for the SIZE command. 
_———— SSE 


MOVE, method 2: Use arrow keys to interactively move the window. If you 
enter the MOVE command without X position and Y position parameters, you 
can use arrow keys to move the window: 


Moves the active window down one line. 

Moves the active window up one line. 

Moves the active window left one character position. 
Moves the active window right one character position. 


VUOBE 


When you're finished using the cursor keys, you must press or : 


For example, if you want to move the COMMAND window up two lines and 
right five characters, you can enter: 


win COM 
move 
Ce) 1c) GO) S&S) SoS YS & (ESC) 
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4.6 Manipulating a Window’s Contents 


Although you may be concerned with changing the way windows appear in the 
display—where they are and how big/small they are—you'll usually be 
interested in something much more important: what's in the windows. Some 
windows contain more information than can be displayed on a screen; others 
contain information that you'd like to change. This section tells you how to view 
the hidden portions of data within a window and which data can be edited. 


EE 
Note: 


Youcan scroll and edit only the active window. For information about select- 
ing the active window, refer to Section 4.4 (page 4-19). 


Scrolling through a window’s contents 


If you resize a window to make it smaller, you may hide information. Some- 
times, a window may contain more information than can be displayed on a 
screen. In these cases, the debugger allows you to scroll information up and 
down within the window. 


There are two ways to view hidden portions of a window's contents: 


[_] You can use the mouse to scroll the contents of the window. 


[_.} You can use function keys and arrow keys. 


SS You can use the mouse to point to the scroll arrows on the righthand side of 
the active window. This is what the scroll arrows look like: 
FILE: sample.c > 
00038 extern call(); 
00039 extern meminit (); eee fall 
00040 main() scro up 
00041 { 
00042 register int i = 0; 
00043 intee=sO0nke=n0); 
00044 
00045 meminit () ; 
00046 for (i = 0, i , 0x50000; i++) 
00047 { 
00048 call (i); 
00049 sive (GL 6 Sj) S$} cea Shp 
aneee Papas) 2 op ee scroll down 
00051 if (!(i & OxFFFF)) k++; 
00052 
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To scroll window contents up or down: 


~ 1) Point to the appropriate scroll arrow. 

i 2) Press the left mouse button; continue to press it until the information you're 

interested in is displayed within the window. 

U0 3) Release the mouse button when you're finished scrolling. 

You can scroll up/down one line at a time by pressing the mouse button and 
releasing it immediately. 

In addition to scrolling, the debugger supports the following methods for 
moving through a window’s contents. 

The page-up key scrolls up through the window contents, one window length 
at atime. You can use (CONTROL) CPAGE UP) to scroll up through an array of struc- 
tures displayed in a DISP window. 

The page-down key scrolls down through the window contents, one window 
length at a time. You can use (CONTROL) (PAGEDOWN)to scroll down through an 
array of structures displayed in a DISP window. 

When the FILE window is active, pressing adjusts the window's con- 
tents so that the first line of the text file is at the top of the window. You can’t 
use outside of the FILE window. 

END When the FILE window is active, pressing adjusts the window’s contents 
so that the last line of the file is at the bottom of the window. You can’t use 
outside of the FILE window. 

a) Pressing this key moves the field cursor up one line at a time. 

© Pressing this key moves the field cursor down one line at a time. 

In the FILE window, pressing this key scrolls the display left eight characters 
at atime. In other windows, moves the field cursor left one field; at the first field 
on a line, wraps back to the last fully displayed field on the previous line. 

In the FILE window, pressing this key scrolls the display right eight characters 


at a time. In other windows, moves the field cursor right one field; at the last 
field on a line, wraps around to the first field on the next line. 
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Editing the data displayed in windows 
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You can edit the data displayed in the MEMORY, CPU, DISP, and WATCH 
windows by using an overwrite “click and type” method or by using commands 
that change the values. (This is described in detail in Section 8.3, Basic 
Methods for Changing Data Values, page 8-4.) 


Note: 


In the following windows, the “click and type” method of selecting data for edit- 
ing— pointing at a line and pressing or the left mouse button—does not 
allow you to modify data. 


J} Inthe FILE and DISASSEMBLY windows, pressing or the mouse but- 
ton sets or clears a breakpoint on any line of code that you select. You 
can’t modify text in a FILE or DISASSEMBLY window. 


J] In the CALLS window, pressing or the mouse button shows the 
source for the function named on the selected line. 


[_] In the PROFILE window, pressing has no effect. Clicking the mouse 
button in the header displays a different set of data; clicking the mouse 
button on an area name shows the code associated with the area. 


Closing a Window 


4.7 Closing a Window 


The debugger opens various windows on the display according to the debug- 
ging mode you select. When you switch modes, the debugger may close some 
windows and open others. Additionally, you may choose to open DISP and 
WATCH windows and additional MEMORY windows. 


Most of the windows remain open—you can’t close them. However, you can 
close the CALLS, DISP, WATCH, and additional MEMORY windows. To close 
one of these windows: 


1) Make the appropriate window active. 


2) Press G4). 


ec 
Note: 


You cannot close the default MEMORY window. 


You can also close the WATCH window by using the WR command: 
wr 


When you close a window, the debugger remembers the window’s size and 
position. The next time you open the window, it will have the same size and 
position. That is, if you close the CALLS window, then reopen it, it will have the 
same size and position as it did before you closed it. Since you can open 
numerous DISP and MEMORY windows, when you open one, it will occupy 
the same position as the last one of that type that you closed. 
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Chapter 5 
Entering and Using Commands 


The debugger provides you with several methods for entering commands: 


[_]} From the command line 
[_] From the pulldown menus (using keyboard combinations or the mouse) 
[__} With function keys 
[_] From a batch file 


Mouse use and function key use differ from situation to situation and are 
described throughout this book whenever applicable. This chapter includes 
specific rules that apply to entering commands and using pulldown menus. 
Also included is information about entering DOS commands and defining your 
own command strings. 


Some restrictions apply to command entry for VAX and Sun versions of the 
simulator. For descriptions of these restrictions, refer to the installation guide. 


Topic Page 
5.1. Entering Commands From the Command Line 5-2 
How to type in and enter commands 5-3 
Sometimes, you can’t type a command 5-4 
Using the command history 5-5 
Clearing the display area 5-5 
Recording information from the display area 5-6 

5.2 Using the Menu Bar and the Pulldown Menus 5-7 
Pulldown menus in the profiling environment 5-8 
Using the pulldown menus 5-8 
Escaping from the pulldown menus 5-9 
Using menu bar selections that don’t have pulldown menus 5-10 

5.3. Using Dialog Boxes 5-11 
Entering text in a dialog box 5-11 
Selecting parameters in a dialog box 5-12 
Closing a dialog box 5-15 

5.4 Entering Commands From a Batch File 5-17 
Echoing strings in a batch file 5-18 
Controlling command execution in a batch file 5-18 

5.5 Defining YourOwn Command Strings 5-21 
5.6 Entering Operating-System Commands (DOS Only) 5-24 
Entering a single command from the debugger command line 5-24 
Entering several command from a system shell 5-25 
Additional system commands 5-25 
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5.1 Entering Commands From the Command Line 


The debugger supports a complete set of commands that help you to control 
and monitor program execution, customize the display, and perform other 
tasks. These commands are discussed in the various sections throughout this 
book, as they apply to the current topic. Chapter 13 summarizes all of the 
debugger commands with an alphabetic reference. 


Although there are a variety of methods for entering most of the commands, 
all of the commands can be entered by typing them on the command line in 
the COMMAND window. Figure 5—1 shows the COMMAND window. 


Figure 5—1. The COMMAND Window 
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COMMAND 


p- 


display 
area TMS320C5x Debugger 

Copyright (c) 1990,1992 

TMS320C5x Revision 1 

jo main v 
command Eat stan 5d _| 
line 


The COMMAND window serves two purposes: 


[_] The command line portion of the window provides you with an area for 
entering commands. For example, the command line in Figure 5—1 shows 
that a STEP command was typed in (but not yet entered). 


(_] The display area provides the debugger with a space for echoing com- 
mands, displaying command output, or displaying errors and messages 
for you to read. For example, the command output in Figure 5-1 shows 
the messages that are displayed when you first bring up the debugger and 
also shows that a GO MAIN command was entered. 


If you enter acommand through an alternate method (using the mouse, a 
pulldown menu, or function keys), the COMMAND window doesn’t echo 
the entered command. 
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How to type in and enter commands 


You can type a command at almost any time; the debugger automatically 
places the text on the command line when you type. When you want to enter 
a command, just type—no matter which window is active. You don’t have to 
worry about making the COMMAND window active or moving the field cursor 
to the command line. When you start to type, the debugger usually assumes 
that you're typing a command and puts the text on the command line (except 
under certain circumstances, which are explained on the next page). 
Commands themselves are not case sensitive, although some parameters 
(such as window names) are. 


To execute a command that you’ve typed, just press @). The debugger then: 


1) Echoes the command to the display area, 
2) Executes the command and displays any resulting output, and 
3) Clears the command line when command execution completes. 


Once you’ve typed a command, you can edit the text on the command line with 
these keystrokes: 


To... Press... 
Move back over text without erasing characters (CONTROL } or 
BACK SPACE 


Move forward through text without erasing characters (CONTROL ) 
Move back over text while erasing characters DEL 


Move forward through text while erasing characters (SPACE) 


Insert text into the characters that are already on the INSERT ) 
command line 


Note: 


[_] You cannot use the arrow keys to move through or edit text on the 
command line. 


[| Typing a command doesn’t make the COMMAND window the active 
window. 


_] If you press when the cursor is in the middle of text, the debugger 
truncates the input text at the point where you press @). 
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Sometimes, you can’t type a command 
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At most times, you can press any alphanumeric or punctuation key on your 
keyboard (any printable character); the debugger interprets this as part of a 
command and displays the character on the command line. Ina few instances, 
however, pressing an alphanumeric key is not interpreted as information for 
the command line. 


I] 


LJ 


When you're pressing the key, typing certain letters causes the 
debugger to display a pulldown menu. 


When a pulldown menu is displayed, typing a letter causes the debugger 
to execute a selection from the menu. 


When you’re pressing the key, pressing or moves the 
command-line cursor backward or forward through the text on the com- 
mand line. 


When you’re editing a field, typing enters a new value in the field. 


When you're using the MOVE or SIZE command interactively, pressing 
keys affects the size or position of the active window. Before you can enter 
any more commands, you must press to terminate the interactive 
moving or sizing. 


When you’ve brought up a dialog box, typing enters a parameter value for 
the current field in the box. Refer to Section 5.3 on page 5-11 for more in- 
formation on dialog boxes. 
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Using the command history 


The debugger keeps an internal list, or command history, of the commands 
that you enter. It remembers the last 50 commands that you entered. If you 
want to re-enter a command, you can move through this list, select a command 
that you've already executed, and re-execute it. 


Use these keystrokes to move through the command history. 


To... Press... 
Repeat the last command that you entered 


Move forward through the list of executed commands, one by one 


Move backward through the list of executed commands, one by one 


As you move through the command history, the debugger displays the 
commands, one by one, on the command line. When you see a command that 
you want to execute, simply press @) to execute the command. You can also 
edit these displayed commands in the same manner that you can edit new 
commands. 


For information about using the PDM’s command history, refer to page 2-13. 


Clearing the display area 


<2 


Occasionally, you may want to completely blank out the display area of the 
COMMAND window; the debugger provides a command for this: 


Use the CLS command to clear all displayed information from the display area. 
The format for this command is: 


cls 
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Recording information from the display area 
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The information shown in the display area of the COMMAND window can be 
written to a log file. The log file is a system file that contains commands you've 
entered, their results, and error or progress messages. To record this informa- 
tion in a log file, use the DLOG command. 


You can execute log files by using the TAKE command. When you use DLOG 
to record the information from the COMMAND window display area, the de- 
bugger automatically precedes all error or progress messages and command 
results with a semicolon to turn them into comments. This way, you can easily 
re-execute the commands in your log file by using the TAKE command. 


(_] To begin recording the information shown in the COMMAND window dis- 
play area, use: 


dlog filename 


This command opens a log file called filename that the information is re- 
corded into. 


(_] To end the recording session, enter: 


dlog close 


If necessary, you can write over existing log files or append additional informa- 
tion to existing files. The extended format for the DLOG command is: 


dlog filename [,{a | w}] 


The optional parameters of the DLOG command control how the log file is 
created and/or used: 


_] Creating a new log file. If you use the DLOG command without one of 
the optional parameters, the debugger creates a new file that it records the 
information into. If you are recording to a log file already, entering a new 
DLOG command and filename closes the previous log file and opens a 
new one. 


_.} Appending to an existing file. Use the a parameter to open an existing 
file to which to append the information in the display area. 


|_| Writing over an existing file. Use the w parameter to open an existing 
file to write over the current contents of the file. Note that this is the default 
action if you specify an existing filename without using either the a or w 
option; you will lose the contents of an existing file if you don’t use the ap- 
pend (a) option. 


For more information about the PDM version of the DLOG command, see 
page 2-10. 
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5.2 Using the Menu Bar and the Pulldown Menus 


In all three of the debugger modes, you'll see a menu bar at the top of the 
screen. The menu selections offer you an alternative method for entering 
many of the debugger commands. Figure 5—2 points out the menu bar in a 
mixed-mode display. There are several ways to use the selections on the 
menu bar, depending on whether the selection has a pulldown menu or not. 


Figure 5—2. The Menu Bar in the Basic Debugger Display 


menu bar 


Break Watch Memory Color Analysis Pin Run=F5 Step=F8 Next=F10 
-—DISASSEMBLY- 1 CPU 
0040 0aao main: POPD a+ acc 00000002 A 
0041 80a0 SAR ARO, *+ RCCR Serene se 
0042 8180 ie PREG 00000000 
cee Euhly PC 0107 
0043 b004 LAR ARO, #4 Tos £050 
0044 00ea LAR ARO, *0+,AR2 ARO 0000 
0045 b900 ZAC ARI o95£ 
0046 b201 LAR AR2, #1 AR2  dffd 
0047 8be0 MAR *0+ \ (eee ee 
‘é AR4 £080 
0048 90a0 SACL + ARS 09c6 v 
-—FILE: sample.c 1 AR6 bEfft 
00046 int *pi; A|ART bftt 
00047 char <xDC};: CALLS 
00048 1: main() 
00049 extern call(); 
00059 exter meminit(); v 
00060 
00061 main() | | 
‘MEMORY 
: 0000 0007 0007 0007 0007 bftt ££00 0000 
file sample.c 
0007 0008 0000 bftt 0000 0000 ooo1 ooo1 
go main 
000e ooo1 DEEL: 0000 o9f5 dffd £LEf £080 v 
0015 09c6 bftt bftt £7££ 0000 bftt bfff£ 
001lc bfftft bftft ££77 bftt 0000 0000 osoo | 


Several of the selections on the menu bar have pulldown menus; if they could 
all be pulled down at once, they’d look like Figure 5-3. 
Figure 5—3. All of the Pulldown Menus (Basic Debugger Display) 
Load Break Watch Memory Color Mode Analysis Pin 
Load Add Add Add Load Cc (auto) Disable Connect 
Reload Delete Delete Delete Save Asm Count Disconnect 
Symbols Reset Reset Reset Config Mixed Break Elsi 
REstart List List Border ea) 
Reset Enable Prompt View 
File ipadla 
Save 
Connect 
DisConn y 
Note: The Pin menu and the Connect and DisConn entries in the Memory menu are available 


for the simulator only. 


Entering and Using Commands 


Using the Menu Bar and the Pulldown Menus 


Note that the menu bar and associated pulldown menus occupy fixed positions 
on the display. Unlike windows, you can’t move, resize, or cover the menu bar 
or pulldown menus. 


Pulldown menus in the profiling environment 


The debugger displays a different menu bar in the profiling environment: 


> 


Load mAp Mark Enable Disable Unmark View Stop-points Profile 


y 


The Load menu corresponds to the Load menu in the basic debugger environ- 
ment. The mAp menu provides memory map commands available from the 
basic Memory menu. The other entries provide access to profiling commands. 


Using the pulldown menus 


There are several ways to display the pulldown menus and then execute your 
selections from them. Executing a command from a menu is similar to execut- 
ing a command by typing it in. 


[_] If you select a command that has no parameters or only optional parame- 
ters, then the debugger executes the command as soon as you select it. 


[__] If you select a command that has one or more required parameters, the 
debugger displays a dialog box when you make your selection. A dialog 
box offers you the chance to type in the parameters values for the com- 
mand. 


The following paragraphs describe several methods for selecting commands 
from the pulldown menus. 


Mouse method 1 


i 1) Point the mouse cursor at one of the appropriate selections in the menu 
bar. 

il 2) Press the left mouse button, but don’t release the button. 

A 3) While pressing the mouse button, move the mouse downward until your 


selection is highlighted on the menu. 


U0 4) When your selection is highlighted, release the mouse button. 
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Mouse method 2 
a 1) Point the cursor at one of the appropriate selections in the menu bar. 


tt 2) Click the left mouse button. This displays the menu until you are ready to 
make a selection. 


x 3) Point the mouse cursor at your selection on the pulldown menu. 


tt 4) When your selection is highlighted, click the left mouse button. 


Ikey| Keyboard method 1 


ALT 1) Press the key; don’t release it. 


& 
bs 


Press the key that corresponds to the highlighted letter in the selection 
name; release both keys. This displays the menu and freezes it. 


3) Press and release the key that corresponds to the highlighted letter of your 
selection in the menu. 


Keyboard method 2 
ALT 1) Press the key; don’t release it. 


OO 2) Press the key that corresponds to the highlighted letter in the selection 
name; release both keys. This displays the menu and freezes it. 


G@) @® 3) Use the arrow keys to move up and down through the menu. 


(2) 4) When your selection is highlighted, press @). 


Escaping from the pulldown menus 


(_] If you display amenu and then decide that you don’t want to make a selec- 
tion from this menu, you can: 


M Press 
or 


HH Point the mouse outside of the menu; press and then release the left 
mouse buiton. 


(_] If you pull down a menu and see that it is not the menu you wanted, you 
can point the mouse at another entry and press the left mouse button, or 
you can use the and keys to display adjacent menus. 


Entering and Using Commands 5-9 


Using the Menu Bar and the Pulldown Menus 


Using menu bar selections that don’t have pulldown menus 


- 


a 


al (FS) 
(Fs) 
F10 


These three menu bar selections are single-level entries without pulldown me- 
nus: 


Run=F5 Step=F8 Next=F10 ) 


There are two ways to execute these choices. 


1) Point the cursor at one of these selections in the menu bar. 


2) Click the left mouse button. 


This executes your choice in the same manner as typing in the associated 
command without its optional expression parameter. 


Pressing this key is equivalent to typing in the RUN command without an 
expression parameter. 


Pressing this key is equivalent to typing in the STEP command without an 
expression parameter. 


Pressing this key is equivalent to typing in the NEXT command without an 
expression parameter. 
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5.3 Using Dialog Boxes 


Many of the debugger commands have parameters. When you execute these 
commands from pulldown menus, you must have some way of providing 
parameter information. The debugger allows you to do this by displaying a 
dialog box that asks for this information. 


Some debugger commands have very simple dialog boxes that provide you 
with an alternative method for typing in values. Other commands, such as 
analysis commands, have more complex dialog boxes; in addition to typing in 
values, you may be asked to make selections from a list of predefined 
parameters. 


Entering text in a dialog box 


Entering text in a dialog box is much like entering commands on the command 
line. For example, the Add entry on the Watch menu is equivalent to entering 
the WA command. This command has three parameters: 


wa expression [,[ label] [, display format] 


When you select Add from the Watch menu, the debugger displays a dialog 
box that asks you for this parameter information. The dialog box looks like this: 


Watch Add 
Expression 
Label 
Format 


<<OK>> <Cancel> 


You can enter an expression just as you would if you were to type the WA 
command; then press or @). The cursor moves down to the next parame- 
ter: 


Watch Add 
Expression MY_VAR 
Label 
Format 


<<OK>> <Cancel> 


When the dialog box displays more than one parameter, you can use the arrow 
keys to move from parameter to parameter. You can omit entries for optional 
parameters, but the debugger won’t allow you to skip required parameters. 
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In the case of the WA command, the two parameters, /abe/and format, are op- 
tional. If you want to enter a parameter, you may do so; if you don’t want to use 
these optional parameters, don’t type anything in their fields—just continue to 
the next parameter. 


Modifying text in a dialog box is similar to editing text on the command line: 


[_} When you display a dialog box for the first time during a debugging ses- 
sion, the parameter fields are empty. When you bring up the same dialog 
box again, though, the box displays the last values that you entered. (This 
is similar to having acommand history.) If you want to use the same value, 
just press or G) to move to the next parameter. 


(_] You can edit what you type (or values that remain from a previous entry) 
in the same way that you can edit text on the command line. See Section 
5.1 for more information on editing text on the command line. 


When you've entered a value for the final parameter, point and click on <OK> 
to save your changes, or on <Cancel> to discard your changes; the debugger 
closes the dialog box and executes the command with the parameter values 
you supplied. You can also choose between the <OK> and <Cancel> options 
by using the arrow keys and pressing on your desired choice. 


Selecting parameters in a dialog box 


More complex dialog boxes, such as those associated with analysis com- 
mands, allow you to: 


(_] Enter text. Entering text ina more complex dialog box is the same as en- 
tering text on the command line. Refer to the discussion above, Entering 
text in a dialog box, for more information. 


_] Choose froma list of predefined options. There are two types of prede- 
fined options in a dialog box. The first type of option allows you to enable 
one or more predefined options. Options of the second type are mutually 
exclusive; therefore, you can enable only one at a time. 


Valid options (of the opened dialog box) are listed for you so that all you 
have to do is point and click to make your selections. 


(_] Close the dialog box. The more complex dialog boxes do not close auto- 
matically. They allow you the option of saving or discarding any changes 
you made to your parameter choices. To close the dialog box, just point 
and click on the appropriate option: either <OK> or <Cancel>. 


Using Dialog Boxes 


Figure 5—4 shows you the components of a complex dialog box used with the 
analysis module. 


Figure 5-4. The Components of a Dialog Box 


Analysis Break Events 


]Program bus [ ]Call taken ]Pipeline clock 
{ ]Branch taken JEmu0 driven low 
defined ]Discontinui rap taken JEmul driven low 
ia. ]Return taken JEvent Counter < 0 
| 
Program bus: )Access (2) 
Address (1) [ )Fgtch (3) 
(4) 
(5) 
)Access (7) 
)Read (8) 
(9) 
text entry 
areas << OK >> < Cancel > 


mutually exclusive 
options closing 
options 


When you display a dialog box for the first time during a debugging session, 
nothing is enabled. When you bring up the same dialog box again, though, 
your previous selections are remembered. (This is similar to having a com- 
mand history.) 


As Figure 5-4 shows, options are preceded by either square brackets or 
parentheses; mutually exclusive options are preceded by parentheses. Enab- 
ling options preceded by square brackets is like turning a switch on and off. 
When the option is enabled, the debugger displays an X inside the brackets 
preceding the option. You can enable as many of these options as you want: 


[X] Option1 []Option2 [X] Option3 
[] Option4  [X]Option5 [X] Option 6 


[X] Option7 []Option8 [] Option 9 
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(i 


ALT 


Mutually exclusive options, however, are enabled when the debugger displays 
an asterisk inside the parentheses preceding your selection. The following ex- 
ample illustrates this: 


(*) Option 1 
() Option 2 


() Option 3 


Notice that only one option is enabled at a time. There are several ways to en- 
able both types of options: 


1) Point the cursor at the option you want to enable. 


2) Click the left mouse button. This enables the event and displays an X next 
to the option (or an asterisk next to a mutually exclusive option). 


Repeat these two steps to disable an option. When the X (or asterisk) is no 
longer displayed, that option has been disabled. 


Keyboard Method 1 
1) Press the key; don’t release it. 


2) Press and release the key that corresponds to the highlighted letter or 
number of the option you want to enable. The debugger displays an X (or 
asterisk) next to the option, indicating that selection is enabled. 


Repeat these two steps to disable an option. When the X (or asterisk) is no 
longer displayed, that option has been disabled. 


TAB 
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Keyboard Method 2 


1) Press the key to move throughout the dialog box until your cursor 
points to the option you want to enable. 


2) Use the arrow keys to move up and down or left and right. 


When you enable a mutually exclusive option, moving the arrow keys alone 
will place an asterisk inside the parentheses, indicating that the option is 
enabled. However, to enable an option preceded by square brackets, you 
must: 


Press the bar. The debugger displays an X next to your selection, thus 
enabling that particular option. 


or 


Press the key. The debugger displays an X next to your selection, thus en- 
abling that particular option. 


Repeat these steps to disable an option. 


Closing a dialog box 


or 


a 


The more complex dialog boxes do not close automatically; the debugger ex- 
pects input from you. When you close a dialog box, you can: 


[_] Save the changes you made 


[_| Discard any of the changes you made 


Note: 


The default option, <OK>, is highlighted; clicking on this option saves your 
changes and closes the dialog box. 


There are several ways to close a dialog box: 


1) Point the cursor at <OK> to close the dialog box and save your changes. 
Or youcan optto discard your changes by pointing the cursor at <Cancel>. 


2) Click the left mouse button. This executes your choice and closes the dia- 
log box. 
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ALT 


& 


TAB 


Keyboard Method 1 
1) Press the key; don’t release it. 


2) Press and release the © key to save your changes. Press and release 
the @ key to discard your changes. Both of these actions execute your 
choice and close the dialog box. 


Keyboard Method 2 


1) Press the key to move through the dialog box until your cursor is in 
the <OK> or <Cancel> field. 


2) Use the arrow keys to switch between <OK> and <Cancel>. 


3) Press the @) key to accept your selection. This executes your choice and 
closes the dialog box. 
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5.4 Entering Commands From a Batch File 


You can place debugger commands in a batch file and execute the file from 
within the debugger environment. This is useful, for example, for setting up a 
memory map that contains several MA commands followed by a MAP 
command to enable memory mapping. 


take Use the TAKE command to tell the debugger to read and execute commands 
4 from a batch file. A batch file can call another batch file; they can be nested 
in this manner up to 10 deep. To halt the debugger’s execution of a batch file, 

press (Esc). 


The format for the TAKE command is: 
take batch filename [, suppress echo flag] 


_] The batch filename parameter identifies the file that contains commands. 


If you supply path information with the filename, the debugger looks 
for the file in the specified directory only. 


lf you don’t supply path information with the filename, the debugger 
looks for the file in the current directory. 


mM OnPCsystems, ifthe debugger can't find the file in the current directo- 
ry, itlooks in any directories that you identified with the D_DIR environ- 
ment variable. You can set D_DIR within the DOS environment; the 
command for doing this is: 


SET D_DIR=pathname;pathname 


This allows you to name several directories that the debugger can 
search. If you often use the same directories, it may be convenient to 
set D_DIR in your autoexec.bat file or initdb.bat file. On DOS systems, 
you can also set D_DIR from within the debugger by using the 
SYSTEM command (see Section 5.6, Entering Operating-System 
Commands, page 5-24). 


_} By default, the debugger echoes the commands in the COMMAND 
window display area and updates the display as it reads commands from 
the batch file. 


Hf you don’t use the suppress echo flag parameter, or if you use it but 
supply a nonzero value, then the debugger behaves in the default 
manner. 


H if youwould like to suppress the echoing and updating, use the value 0 
for the suppress echo flag parameter. 


For information about the PDM version of the TAKE command, see page 2-9. 
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Echoing strings in a batch file 


When executing a batch file, you can display a string to the COMMAND win- 
dow by using the ECHO command. The syntax for the command is: 


echo string 
This displays the string in the COMMAND window display area. 


For example, you may want to document what is happening during the execu- 
tion of a certain batch file. To do this, you could use the following line in your 
batch file to indicate that you are creating anew memory map for your device: 


echo Creating new memory map 


(Notice that the string should not be in quotes.) 


When you execute the batch file, the following message appears: 
eseating new memory map 


Note that any leading blanks in your string are removed when the ECHO com- 
mand is executed. 


For more information about the PDM version of the ECHO command, see 
page 2-12. 


Controlling command execution in a batch file 


In batch files, you can control the flow of debugger commands. You can 
choose to execute debugger commands conditionally or set up a looping situa- 
tion by using IF/ELSE/ENDIF or LOOP/ENDLOOP, respectively. 


[_} To conditionally execute debugger commands in a batch file, use the 
IF/ELSE/ENDIF commands. The syntax is: 


if Boolean expression 
debugger command 
debugger command 


[else 

debugger command 
debugger command 
| 


endif 
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The debugger includes some predefined constants for use with IF. These 
constants evaluate to 0 (false) or 1 (true). Table 5-1 shows the constants 
and their corresponding tools. 


Table 5—1. Predefined Constants for Use With Conditional Commands 


Constant Debugger Tool 
$$EMU$$ emulator 

$$EVM$$ evaluation module (EVM) 
$$SIM$$ simulator 


If the Boolean expression evaluates to true (1), the debugger executes all 
commands between the IF and ELSE or ENDIF. Note that the ELSE por- 
tion of the command is optional. (See Chapter 14 for more information 
about expressions and expression analysis.) 


One way you can use these predefined constants is to create an initializa- 
tion batch file that works for any debugger tool. This is useful if you are us- 
ing, for example, both the emulator and the EVM. To do this, you can set up 
the following batch file: 


if SSEMUS$$ 

echo Invoking initialization batch file for emulator. 
use \cSxhll 

take emuinit.cmd 


endif 
if S$SEVMS$$ 
echo Invoking initialization batch file for EVM. 


use \c5xhll 
take evminit.cmd 


endif 


In this example, the debugger will execute only the initialization com- 
mands that apply to the debugger tool that you invoke. 


Entering and Using Commands 5-19 


Entering Commands From a Batch File 


5-20 


(_} To set up a looping situation to execute debugger commands in a batch 
file, use the LOOP/ENDLOOP commands. The syntax is: 


loop expression 
debugger command 
debugger command 


endloop 


These looping commands evaluate in the same method as in the run 
conditional command expression. (See Chapter 14 for more information 
about expressions and expression analysis.) 


If you use an expression that is not Boolean, the debugger evaluates 
the expression as a loop count. For example, if you wanted to execute 
a sequence of debugger commands ten times, you would use the fol- 
lowing: 


loop 10 
runb 


endloop 


The debugger treats the 10 as a counter and executes the debugger 
commands ten times. 


If you use a Boolean expression, the debugger executes the com- 
mands repeatedly as long as the expression is true. This type of ex- 
pression has one of the following operators as the highest precedence 
operator in the expression: 


For example, if you want to trace some register values continuously, 
you can set up a looping expression like the following: 


loop !0 
step 
? PC 
? ARO 
endloop 
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The IF/ELSE/ENDIF and LOOP/ENDLOOP commands work with the follow- 
ing conditions: 


[_] You can use conditional and looping commands only in a batch file. 


[_] You must enter each debugger command on a separate line in the batch 
file. 


[_} You can’t nest conditional and looping commands within the same batch 
file. 


See Controlling PDM command execution, page 2-10, for more information 
about the PDM versions of the IF and LOOP commands. 


5.5 Defining YourOwn Command Strings 


The debugger provides a shorthand method of entering often-used com- 
mands or command sequences. This processing is called aliasing. Aliasing 
enables you to define an alias name for the command(s) and then enter the 
alias name as if it were a debugger command. 


To do this, use the ALIAS command. The syntax for this command is: 
alias [alias name [, “command string’) | 


The primary purpose of the ALIAS command is to associate the alias name 
with the debugger command you've supplied as the command string. Howev- 
er, the ALIAS command is versatile and can be used in several ways: 


_} Aliasing several commands. The command string can contain more 
than one debugger command—just separate the commands with semi- 
colons. 


For example, suppose you always began a debugging session by loading 
the same object file, displaying the same C source file, and running to a 
certain point in the code. You could define an alias to do all these tasks at 
once: 


alias init,”load test.out;file source.c;go main” 


Now you could enter init instead of the three commands listed within the 
quote marks. 
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(_] Supplying parameters to the command siring. The command string 


can define parameters that you'll supply later. To do this, use a percent 
sign and anumber (%1) to represent the parameter that will be filled in lat- 
er. The numbers should be consecutive (%1, %2, %3) unless you plan to 
reuse the same parameter value for multiple commands. 


For example, suppose that every time you filled an area of memory, you 
also wanted to display that block in the MEMORY window: 

alias mfil,”fill %1, %2, %3, %S4;mem $1” 

Then you could enter: 

mfil Oxff80,1,0x18,0x1122 

The first value (Oxff80) would be substituted for the first FILL parameter 
and the MEM parameter (%1). The second, third, and fourth values would 


be substituted for the second, third, and fourth FILL parameters (%2, %3, 
and %4). 


Listing all aliases. To display a list of all the defined aliases, enter the 
ALIAS command with no parameters. The debugger will list the aliases 
and their definitions in the COMMAND window. 


For example, assume that the init and mfil aliases had been defined as 
shown in the previous two examples. If you enter: 


alias 
you'll see: 
Alias Command 
ILIN IED -—-> load test.out;file source.c;go main 
MFIL —--> fi11 %1,%2,%3,%4;mem $1 


Finding the definition of an alias. If you know an alias name but are not 
sure of its current definition, enter the ALIAS command with just an alias 
name. The debugger will display the definition in the COMMAND window. 


For example, if you had defined the init alias as shown in the first example 
above, you could enter: 


alias init 


Then you'd see: 


“one aliasedas ”"loadtest.out; file source.c;go cao | 


Defining Your Own Command Strings 


_} Nesting alias definitions. You can include a defined alias name in the 
command string of another alias definition. This is especially useful when 
the command string would be longer than the debugger command line. 


[|_| Redefining an alias. To redefine an alias, re-enter the ALIAS command 
with the same alias name and a new command string. 


[|_| Deleting aliases. To delete a single alias, use the UNALIAS command: 
unalias alias name 


To delete al/ aliases, enter the UNALIAS command with an asterisk 
instead of an alias name: 
unalias * 


Note that the * symbol does not work as a wildcard. 


Note: Limitations of Alias Definitions 


[_] Alias definitions are lost when you exit the debugger. If you want to reuse 
aliases, define them in a batch file. 


[_] Individual commands within a command string are limited to an expand- 
ed length of 132 characters. The expanded length of the command 
includes the length of any substituted parameter values. 


For information about the PDM versions of the ALIAS and UNALIAS com- 
mands, see page 2-15. 
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Entering Operating-System Commands (DOS Only) 


5.6 Entering Operating-System Commands (DOS Only) 


The debugger provides a simple method of entering DOS commands without 
explicitly exiting the debugger environment. To do this, use the SYSTEM com- 
mand. The format for this command is: 


system [DOS command , flag] ] 


The SYSTEM command behaves in one of two ways, depending on whether 
or not you supply an operating-system command as a parameter: 


L] Ifyou enter the SYSTEM command with aDOS command as a parameter, 
then you stay within the debugger environment. 


_} If you enter the SYSTEM command without parameters, the debugger 
opens a system shell. This means that the debugger will blank the debug- 
ger display and temporarily exit to the operating-system prompt. 


Use the first method when you have only one command to enter; use the 
second method when you have several commands to enter. 


Entering a single command from the debugger command line 
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If you need to enter only a single DOS command, supply it as a parameter to 
the SYSTEM command. For example, if you want to copy a file from another 
directory into the current directory, enter: 

system "copy a:\backup\sample.c sample.c” 

If the DOS command produces a display of some sort (such as a message), 
the debugger will blank the upper portion of the debugger display to show the 
information. In this situation, you can use the flag parameter to tell the debug- 
ger whether or not it should hesitate after displaying the results of the DOS 
command. Flag may be aO ora 1: 


0 The debugger immediately returns to the debugger environment after 
the last item of information is displayed. 


1 The debugger does not return to the debugger environment until you 
press @). (This is the default.) 


In the preceding example, the debugger would open a system shell to display 
the following message: 


1 File(s) copied 
Type Carriage Return To Return To Debugger 


The message would be displayed until you pressed @). 


If you wanted the debugger to display the message and then return immediate- 
ly to the debugger environment, you could enter the command in this way: 


system "copy a:\backup\sample.c sample.c”,0 
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Entering several commands from a system shell 


If you need to enter several commands, enter the SYSTEM command without 
parameters. The debugger will open a system shell and display the DOS 
prompt. At this point, you can enter any DOS command. 


When you are finished entering commands and are ready to return to the 
debugger environment, enter: 


exit 


Cc OOO 
Note: 


Available memory may limit the DOS commands that you can enter from a 
system shell. For example, you would not be able to invoke another version 
of the debugger. 
| | 
For information about the PDM version of the SYSTEM command, see page 
2-16. 


Additional system commands 


ne 
<a 


or 


dir 


The debugger also provides separate commands for changing directories and 
for listing the contents of a directory. 


Use the CHDIR (CD) command to change the current working directory. The 
format for this command is: 


chdir directory name 
cd_ directory name 


This changes the current directory to the specified directory name. You can 
use relative pathnames as part of the directory name. Note that this command 
can affect any command whose parameter is a filename (such as the FILE, 
LOAD, and TAKE commands). 


Use the DIR command to list the contents of a directory. The format for this 
command is: 
dir [directory name] 


This command displays a directory listing in the display area of the COMMAND 
window. If you use the optional directory name parameter, the debugger 
displays a list of the specified directory’s contents. If you don’t use this 
parameter, the debugger lists the contents of the current directory. 


You can use wildcards as part of the directory name. 
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Defining a Memory Map 


Before you begin a debugging session, you must supply the debugger with a 
memory map. The memory map tells the debugger which areas of memory it 
can and can’t access. Note that the commands described in this chapter can 
also be entered by using the Memory pulldown menu. 
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The Memory Map: What It Is and Why You Must Define It 


6.1 The Memory Map: What It Is and Why You Must Define It 


A memory map tells the debugger which areas of memory it can and can't 
access. Memory maps vary, depending on the application. Typically, the map 
matches the MEMORY definition in your linker command file. 


Note: 


When the debugger compares memory accesses against the memory map, 
it performs this checking in software, not hardware. The debugger can’t 
prevent your program from attempting to access nonexistent memory. 


A special default initialization batch file included with the debugger package 
defines a memory map for your version of the debugger. This memory map 
may be sufficient when you first begin using the debugger. However, the de- 
bugger provides a complete set of memory-mapping commands that let you 
modify the default memory map or define a new memory map. 


You can define the memory map interactively by entering the memory-map- 
ping commands while you’re using the debugger. This can be inconvenient be- 
cause, in most cases, you'll set up one memory map before you begin debug- 
ging and will use this map for all of your debugging sessions. The easiest 
method for defining a memory map is to put the memory-mapping commands 
in a batch file. 


Defining the memory map in a batch file 
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There are two methods for defining the memory map in a batch file: 


[.} You can redefine the memory map defined in the initialization batch file. 


[_] You can define a memory map in a separate batch file of your own. 


When you invoke the debugger, it follows these steps to find the batch file that 
defines your memory map: 


1) Itchecks to see whether you’ve used the -t debugger option. The -t option 
allows you to specify a batch file other than the initialization batch file 
shipped with the debugger. If it finds the -t option, the debugger reads and 
executes the specified file. 


2) If you don’t use the -t option, the debugger looks for the default initializa- 
tion batch file called init.cmd. If the debugger finds this file, it reads and 
executes the commands. 
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Potential memory map problems 


You may experience these problems if the memory map isn’t correctly defined 
and enabled: 


[_} Accessing invalid memory addresses. If you don’t supply a batch file 
containing memory-map commands, then the debugger is initially unable 
to access any target memory locations. Invalid memory addresses and 
their contents are highlighted in the data-display windows. (On color moni- 
tors, invalid memory locations, by default, are displayed in red.) 


[_] Accessing an undefined or protected area. When memory mapping is 
enabled, the debugger checks each of its memory accesses against the 
memory map. If you attempt to access an undefined or protected area, the 
debugger displays an error message. 


(_] Loading aCOFF file with sections that cross amemory range. Be sure 
that the map ranges you specify ina COFF file match those that you define 
with the MA command (described on page 6-5). Alternatively, you can 
turn memory mapping off during a load by using the MAP OFF command 
(see page 6-7). 


6.2 A Sample Memory Map 


Because you must define a memory map before you can run any programs, 
it's convenient to define the memory map in the initialization batch files. 
Figure 6—1 shows the memory map commands that are defined in the initial- 
ization batch file that accompanies the EVM. If you are using the EVM, youcan 
use the file as is, edit it, or create your own memory map batch file. The files 
shipped with the simulator and emulator are similar to that of the EVM. 


Figure 6—1. Memory Map Commands in the Sample Initialization Batch File for the EVM 


MA 0x0000, 0, 0x0800, RAM 
MA 0x0800, 0, 0x2400, RAM 
MA 0x2c00, 0, 0x5400, RAM 
MA 0x0004, 1, Ox001f, RAM 
MA 0x0024, 1, 0x0003, RAM 
MA 0x0028, 1, 0x0003, RAM 
MA 0x0030, 1, 0x0006, RAM 
MA 0x0050, 1, 0x0010, RAM 
MA 0x0060, 1, 0x0020, RAM 
MA 0x0300, 1, 0x0200, RAM 
MA 0x0800, 1, 0x2400, RAM 
MA 0x8000, 1, 0x8000, RAM 
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A Sample Memory Map 


The MA (map add) commands define valid memory ranges and identify the 
read/write characteristics of the memory ranges. Figure 6-2 illustrates the 
memory map defined by the default initialization batch file. 


Figure 6—2. Sample Memory Map for Use With a ’C5x EVM 


Page 0—Program Memory Page 1—Data Memory 

0x0000 0x0000 

to Ox07FE External RAM reserved to 0x0003 

0x0800 Memory Map 0x0004 

to OXOBFF inert AM Registers 4-31 _| to 0x0022 

0x2C00 External RAM reserved 0x0023 
to Ox7FFF 

Memory Map 0x0024 

Registers 36-38 | to 0x0026 

reserved 0x0027 

Memory Map 0x0028 

Registers 40-42 to 0x002A 

0x002B 

ip to 0x002F 

Memory Map 0x0030 

Registers 48-53 to 0x0035 

hebtde 0x0036 

the to 0x004F 

Memory Map Reg. 0x0050 

80-95; I/O Ports | to 0x005F 

F 0x0060 

On-Chip RAM B2 to 0x007F 

0x0080 

ad, to Ox02FF 

F 0x0300 

On-Chip RAM B1 to Ox04FF 

0x0500 

S9HG9 to Ox07FF 

0x0800 

Internal RAM ey Oelde 

4 0x2C00 

OFT, to Ox7FFF 

0x8000 

External RAM ie Occare 


6-4 


Identifying Usable Memory Ranges 


6.3 Identifying Usable Memory Ranges 


me 
<4 


The debugger’s MA (memory add) command identifies valid ranges of target 
memory. The syntax for this command is: 


ma_ address, page, length, type 


[_} The address parameter defines the starting address of a range. This 
parameter can be an absolute address, any C expression, the name of a 
C function, or an assembly language label. 


A new memory map must not overlap an existing entry. If you define a 
range that overlaps an existing range, the debugger ignores the new 
range and displays this error message in the COMMAND window display 
area: 


Conflicting map range 


(_] The page parameter is a one-digit number that identifies the type of 
memory (program, data, or I/O) that the range occupies: 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


[|_| The /ength parameter defines the length of the range. This parameter can 
be any C expression. 


[|_|] The type parameter identifies the read/write characteristics of the memory 
range. The type must be one of these keywords: 


Use this keyword as the type 


To identify this kind of memory, parameter 
Read-only memory R or ROM 
Write-only memory W or WOM 
Read/write memory R|W or RAM 
No-access memory PROTECT 
Input port IPORT 
Output port OPORT 
Input/output port IOPORT 
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Notes: 


(_} The debugger caches memory that is not defined as a port type (IPORT, 
OPORT, or IOPORT). For ranges that you don’t want cached, be sure 
to map them as ports. 


(_} When you are using the simulator, you can use the parameter values 
IPORT, OPORT, and IOPORT to simulate I/O ports. See Section 6.8, 
Simulating I/O Space. 


[_] Be sure that the map ranges that you specify ina COFF file match those 
that you define with the MA command. Moreover, a command sequence 
such as: 


ma x,0,y,ram; ma xt+y,0,z,ram 

doesn’t equal 

ma x,0,y+z,ram 

If you were planning to load a COFF block that spanned the length of 
y + Z, you should use the second MA command example. Alternatively, 


you could turn memory mapping off during aload by using the MAP OFF 


command. 
ee 


Memory mapping with the simulator 


Unlike the emulator and EVM, the ’C5x simulator has memory cache capabili- 
ties that allow you to allocate as much memory as you need. However, to use 
memory cache capabilities effectively with the ’C5x, do not allocate more than 
20K words of memory in your memory map. For example, the following 
memory map allocates 64K words of ’C5x program memory. 


Example 6—1.Sample Memory Map for the TMS320C5x Using Memory Cache Capabilities 
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IA 0,0,0x5000,R|W 

IA 0x5000,0,0x5000,R|W 
1A 0xa000,0,0x5000,R|W 
MA 0xf000,0,0x1000,R|W 


ses 


The simulator creates temporary files in a separate directory on your disk. For 
example, when you enter an MA (memory add) command, the simulator 
creates a temporary file in the root directory of your current disk. Therefore, 
if you are currently running your simulator on the C drive, temporary files are 
placed in the C:\ directory. This prevents the processor from running out of 
memory space while you are executing the simulator. 
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EF _ ———_— | $s S$ @»®™ ™ ’€|™€’€=ao—VoaoQ —0.0.®™—<—<\ . .—. .. 4] 
Note: 


If you execute the simulator from a floppy drive (for example, drive A), the 
temporary files will be created in the A:\ directory. 
| | 
Alltemporary files are deleted when you leave the simulator via the QUIT com- 
mand. If, however, you exit the simulator with a soft reboot of your computer, 
the temporary files will not be deleted; you must delete these files manually. 
(Temporary files usually have numbers for names.) 


Your memory map is now restricted only by your PC’s capabilities. As a result, 
there should be sufficient free space on your disk to run any memory map you 
want to use. If you use the MA command to allocate 20K words (40K bytes) 
of memory in your memory map, then your disk should have at least 40K bytes 
of free space available. To do this, you can enter: 


ma 0x0, 0, 0x5000, ram 


Note: 


You can also use the memory cache capability feature for the data memory. 


6.4 Enabling Memory Mapping 


<a 


or 


By default, mapping is enabled when you invoke the debugger. In some 
instances, you may want to explicitly enable or disable memory. You can use 
the MAP command to do this; the syntax for this command is: 


map on 
map off 


Note that disabling memory mapping can cause bus fault problems in the 
target because the debugger may attempt to access nonexistent memory. 


Note: 


When memory mapping is enabled, you cannot: 


[_] Access memory locations that are not defined by an MA command 


[_| Modify memory areas that are defined as read only or protected 


If you attempt to access memory in these situations, the debugger displays 
this message in the COMMAND window display area: 


Error in expression 
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Checking the Memory Map 
6.5 Checking the Memory Map 


~@ ml If you want to see which memory ranges are defined, use the ML command. 
s The syntax for this command is: 


ml 


The ML command lists the page, starting address, ending address, and read/ 
write characteristics of each defined memory range. For example, if you’re 
using the EVM default memory map and you enter the ML command, the 
debugger displays this: 


Memory range Attributes 
0000 Oise READ WRITE 
0800 AONEAE REA RITE 
0800 AONEAE REA RITE 
2c00 YsEsE iE REA RITE 
8000 IE IE AEE REA RITE 
0004 0022 REA RITE 
0024 0026 REA RITE 
0028 002a REA RITE 
0030 0035 REA RITE 
0050 OO5f REA RITE 


va il 0060 - OO7£ READ WRITE 
dl 0300 O4ff REA RITE 
Page 0 = program memory 

Page 1 = data memory starting address ending address 


SSS2a222222222 
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6.6 Modifying the Memory Map During a Debugging Session 


md 


ma 


If you need to modify the memory map during a debugging session, use these 
commands. 


To delete a range of memory from the memory map, use the MD (memory 
delete) command. The syntax for this command is: 


md_ address, page 


_} The address parameter identifies the starting address of the range of 
program, data, or I/O memory. If you supply an address that is not the 
starting address of a range, the debugger displays this error message in 
the COMMAND window display area: 


Specified map not found 


J The page parameter is a one-digit number that identifies the type of 
memory (program, data, or I/O) that the range occupies: 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


ae | 


Note: 


If you are using the simulator and want to use the MD command to remove 
a simulated I/O port, you must first disconnect the port with the MI command. 
Refer to Section 6.8, page 6-11. 


eeeeee eee sss) 


If you want to delete all defined memory ranges from the memory map, use 
the MR (memory reset) command. The syntax for this command is: 


mr 
This resets the debugger memory map. 


If you want to add a memory range to the memory map, use the MA (memory 
add) command. The syntax for this command is: 


ma_ address, page, length, type 


The MA command is described in detail on page 6-5. 
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Returning to the original memory map 


If you modify the memory map, you may want to go back to the original memory 
map without quitting and reinvoking the debugger. You can do this by resetting 
the memory map and then using the TAKE command to read in your original 
memory map from a batch file. 


Suppose, for example, that you had set up your memory map in a batch file 
named mem.map. You could enter these commands to go back to this map: 


mr Reset the memory map 
take mem.map Reread the default memory map 


The MR command resets the memory map. (Note that you could put the MR 
command in the batch file, preceding the commands that define the memory 
map.) The TAKE command tells the debugger to execute commands from the 
specified batch file. 


6.7 Using Multiple Memory Maps for Multiple Target Systems 


If you’re debugging multiple applications, you may need a memory map for 
each target system. Here’s the simplest method for handling this situation. 


Step 1: Let the initialization batch file define the memory map for one of your 
applications. 


Step 2: Create a separate batch file that defines the memory map for the 
additional target system. The filename is unimportant, but for the 
purposes of this example, assume that the file is named filename.x. 
The general format of this file’s contents should be: 


mr Reset the memory map 
MA commands Define the new memory map 
map on Enable mapping 


(Of course, you can include any other appropriate commands in this 
batch file.) 


Step 3: Invoke the debugger as usual. 

Step 4: The debugger reads initialization batch file during invocation. Before 
you begin debugging, read in the commands from the new batch file: 
take filename.x 
This redefines the memory map for the current debugging session. 


You can also use the -t option instead of the TAKE command when 
you invoke the debugger. The -t option allows you to specify a new 
batch file to be used instead of the default initialization batch file. 
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6.8 Simulating I/O Space (Simulator Only) 


In addition to adding memory ranges to the memory map, you can use the MA 
command to add I/O ports to the memory map. To do this, use IPORT (input 
port), OPORT (output port), or IOPORT (input/output port) as the memory 
type. Use page 1 to simulate serial ports; use page 2 to simulate parallel ports. 
Then, you can use the MC command to connect a port to an input or output 
file. This simulates external I/O cycle reads and writes by allowing you to read 
data in from a file and/or write data out to a file. 


Connecting an I/O port 


sie 


The MC (memory connect) command connects IPORT, OPORT, or IOPORT 
to an input or output file. The syntax for this command is: 


mc_ port address, page, filename, {READ | WRITE} 


[_} The port address parameter defines the address of the I/O port. This 
parameter can be an absolute address, any C expression, the name of a 
C function, or an assembly language label. 


J The page parameter is a one-digit number that identifies the page that the 
port occupies. Parallel ports are on page 2 (the I/O space), and serial ports 
are on page 1 (data space). 


[__] The filename parameter can be any filename. If you connect a port to read 
from a file, the file must exist, or the MC command will fail. 


[|_| The final parameter is specified as READ or WRITE and defines how the 
file will be used (for input or output, respectively). 


The file is accessed during an IN or OUT instruction to the associated port 
address. Any port in I/O space can be connected to a file. A maximum of one 
input and one output file can be connected to a single port; multiple ports can 
be connected to a single file. Memory-mapped ports can also be connected 
to files; any instruction that reads or writes to the memory-mapped port will 
read or write to the associated file. 


Example 6—2 shows how an input port can be connected to an input file named 
in.dat. 


Defining a Memory Map 6-11 


Simulating I/O Space (Simulator Only) 


Example 6—2.Connecting an Input Port to an Input File 


Assume that the file in.dat contains words of data in hexadecimal format, 
one per line, like this: 


OAOO 
1000 
2000 


These two debugger instructions set up and connect an input port: 


MA 0x50,1,0x1,IPORT Configure port address 50h 
as an input port 
MC 0x50,1,in.dat, READ Open file in.dat and 


connect to port address 50h 


Assume that these two ’C5x instructions are part of your ’C5x program. 
They read from the file in.dat. 


IN 00h, 50h IN instruction reads from file 
LAMM 50h Memory reference load 
used to read from file 


Observing serial port data 


The simulator provides serial port simulation for both the standard 
synchronous serial port and the TDM serial port in either TDM or standard 
operation mode. You can connect the ports to input and output files by using 
the memory-connect pseudoregisters. To observe the data moving in and out 
of the ports, use the WA command. Table 6—1 lists the pseudoregisters that 
you can watch. 
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Table 6—1. Serial Port Pseudoregisters 


Pseudo- 
register 


XIRP 


XIRT 


RIRP 


RIRT 


TXIRP 


TXIRT 


TRIRP 


TRIRT 


Description 
Transmit Interrupt Period Register 


Defines the machine cycles between transmit interrupts. The period is loaded 
into the transmit interrupt timer register (XIRT) when the serial ports are reset 
or when XIRT decrements to zero. Once the XIRT register counter reaches 
zero, data is transferred from the DXR register to the file that is connected to 
this register. A transmit interrupt is set in the interrupt flag register. If the inter- 
rupt is masked in the interrupt mask register, or if the global interrupt mode 
(INTM) is disabled, the transfer will not occur. 


Transmit Interrupt Timer Register 


Contains the current cycle count time to the next transmit interrupt. The count- 
er decrements at the machine cycle rate. 


Receive Interrupt Period Register 


Defines the machine cycles between receive interrupts. The period is loaded 
into the receive interrupt timer register (RIRT) when the serial ports are reset 
or when RIRT decrements to zero. Once the RIRT counter reaches zero, data 
is transferred from the file that is connected to the register to the data memory 
location. A receive interrupt is set in the interrupt flag register. If the interrupt 
is masked in the interrupt mask register, or if the global interrupt mode (INTM) 
is disabled, the transfer will not occur. 


Receive Interrupt Timer Register 


Contains the current cycle count time to the next receive interrupt. The counter 
decrements at the machine cycle rate. 


Standalone Mode TDM Transmit Interrupt Period Register 


Controls operation of the TDM serial port operating in standard serial port 
mode. The operation is identical to the description of the XIRP register. 


Standalone Mode TDM Transmit Interrupt Timer Register 


Controls operation of the TDM serial port operating in standard serial port 
mode. The operation is identical to the description of the XIRT register. 


Standalone Mode TDM Receive Interrupt Period Register 


Controls operation of the TDM serial port operating in standard serial port 
mode. The operation is identical to the description of the RIRP register. 


Standalone Mode TDM Receive Interrupt Timer Register 


Controls operation of the TDM serial port operating in standard serial port 
mode. The operation is identical to the description of the RIRT register. 


Default 
64 


Loaded from XIRP 


64 


Loaded from XIRT 


Yes 


Default 64 


Loaded from XIRP 


64 


Loaded from XIRT 
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Table 6-1. Serial Port Pseudoregisters (Continued) 


Pseudo- 
register 


TDMP 


TDMT 


Description 
TDM Serial Port Period Register 


Defines the number of machine cycles between the start of each set of eight 
channels. The minimum period allowed is 512 cycles, equivalent to the maxi- 
mum rate of the TDM port. The period is loaded into the TDM serial port timer 
register (TDMT) when the serial ports are reset or when the TDMT decre- 
ments to zero. Once the TDMT count reaches zero, a block of eight TDM re- 
ceive and transmit operations begins, each delayed by 64 machine cycles. 
For the transmit operations, the data in TDXR will be transferred to the file con- 
nected to that register. The transfer will occur only if the device is configured 
to transmitin thattime slot, interrupts are enabled, and the mask register (IMR) 
is set properly. For each occurrence of TDMT decrementing to zero, eight 
lines of data are read from the file. The data is transferred to the TDM receive 
register, TRCV, if the TADD receive address and TRTA bits are properly set. 
The transfer will occur only if interrupts are enabled and the IMR is properly 
set. 


TDM Serial Port Timer Register 


Contains the current cycle count time to the next set of eight TDM transfers. 
The counter decrements at the machine cycle rate. 


Configuring memory to use serial port simulation 


Default 
512 


Loaded from 
TDMP 


In order to use the serial port simulation, you must configure memory with the 
MA and MC commands. The following example adds the transmit and receive 
registers to the memory map and then connects their input and output to a file: 


Example 6-3. Adding Transmit and Receive Registers; Connecting Their Input and Output 


to a File 

ma 0x20,1,1,IPORT ;Configure DRR in data space as input port 

may 0x2 OPORT ;Configure DXR in data space as output port 

ma; 0x30), 71, LERORT ;Configure TRCV in data space as input port 

may OsS 177 17 OPORT ;Configure TDXR in data space as output port 

mc 0x20,1,rdat, read ;Open file rdat and connect to port address 20h 
mc 0x21,1,xdat,write ;Open file xdat and connect to port address 21h 
mc 0x30,1,trdat, read ;Open file trdat and connect to port address 30h 
me Oxsiyllexdatp write ;open file txdat and connect to port address 31h 
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The following commands configure the period registers for the transmit and 
receive operations to occur every 64 cycles for the standard serial port, and 
every 512 cycles for the TDM serial port: 

?rirp=64 


?xirp=64 
?tdmp=512 


The input and output file formats for the standard serial port operation require 
one hexadecimal number per line. The following is an acceptable format for 
an input file to the standard serial port: 


0000 
a445 
099f 


For the TDM serial port operation, the input and output file formats require 
three fields: address, data, and channel number. Each field must be in hexi- 
decimal format, separated by spaces. The following is an acceptable format 
for an input file to the TDM serial port: 


80 o123. 0 
40 4567 1 
20 89ab 2 
10 cdef 3 
01 0123 4 


Disconnecting an I/O port 


Before you can use the MD command to delete a port from the memory map, 
you must use the MI command to disconnect the port. 


The MI (memory disconnect) command disconnects a file from an I/O port. The 


FE} = tettimenor dscomesiconnanddscomessatieromantO por The 


syntax for this command is: 
mi port address, page, {READ | WRITE} 


The port address and page identify the port that will be closed. The read/write 
characteristics must match the parameter used when the port was connected. 
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6.9 Simulating External Interrupts (Simulator Only) 


The ’C5x simulator allows you to simulate the external interrupt signals INT1 
- INT4 and to select the clock cycle where you want an interrupt to occur. To 
do this, you create a data file and connect it to one of the four interrupt pins, 
INT1-INT4, or the BIO pin. 


Note: 


The time interval is expressed as a function of CPU clock cycles. Simulation 
begins at the first clock cycle. 


Cd 


Setting up your input file 


In order to simulate interrupts, you must first set up an input file that lists inter- 
rupt intervals. Your file must contain a clock cycle in the following format: 


[clock cycle, logic value] rpt {n | EOS} 
Note that the square brackets are used only with logic values for the BIO pin. 


[_} The clock cycle parameter represents the CPU clock cycle where you 
want an interrupt to occur. 


You can have two types of CPU clock cycles: 


HM Absolute. To use an absolute clock cycle, your cycle value must rep- 
resent the actual CPU clock cycle where you want to simulate an inter- 
rupt. For example: 


12 34 56 


Interrupts are simulated at the 12th, 34th, and 56th CPU clock cycles. 
Notice that no operation is done to the clock cycle value; the interrupt 
occurs exactly as the clock cycle value is written. 


H@ Relative. You can also select a clock cycle thatis relative to the time at 
which the last event occurred. For example: 


12 +34 55 


In this example, a total of three interrupts are simulated at the 12th, 
46th (12+34), and 55th CPU clock cycles. A plus sign (+) before a 
clock cycle adds that value to the total clock cycles preceding it. 
Notice that you can mix both relative and absolute values in your input 
file. 


Simulating External Interrupts (Simulator Only) 


[J The /ogic value parameter is only for the BIO pin. You must use a value 
to force the signal to go high or low at the corresponding clock cycle. A val- 
ue of 1 forces the signal to go high, and a value of 0 forces the signal to 
go low. For example: 


[i2,1] §23,0] F45;,4] 


This causes the BIO pin to go high at the 12th cycle, low at the 23rd cycle, 
and high again at the 45th cycle. 


_] The rpt{n | EOS} parameter is optional and represents a repetition value. 
You can have two forms of repetition to simulate interrupts: 


HM Repetition on a fixed number of times. You can format your input 
file to repeat a particular pattern for a fixed number of times. For exam- 


ple: 
5 (+10 +20) rpt 2 


The values inside of the parentheses represent the portion that is 
repeated. Therefore, an interrupt is simulated at the 5th CPU cycle, 
then the15th (5+10), 35th (15+20), 45th (35+10), and 65th (45+20) 
CPU clock cycles. 


Note that n is a positive integer value. 


H Repetition to the end of simulation. To repeat the same pattern 
throughout the simulation, add the string EOS to the line. For example: 


10 (+5 +20) rpt EOS 


Interrupts are simulated at the 10th CPU cycle, then the 15th (10+5), 
35th = (15+20), 40th (35+5), 60th (40+20), 65th (60+5), and 85th 
(65+20) CPU cycles, continuing in that pattern until the end of 
simulation. 
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Programming the simulator 


After you have created your input file, you can use debugger commands to 
connect, list, and disconnect the interrupt pin to your input file. Use these com- 
mands as described below, or use them from the PIN pulldown menu. 


pinc Toconnect your input file to the pin, use the following command: 
<a 


pinc pinname, filename 


|_| The pinname identifies the pin and must be one of four simulated pins 
(INT1-INT4) or the BIO pin. 


[__] The filename is the name of your input file. 


Example 6—4 shows you how to connect your input file using the PINC com- 
mand. 


Example 6-4. Connecting the Input File With the PINC Command 


Suppose you want to generate an INT2 external interrupt at the 12th, 34th, 
56th, and 89th clock cycles. 


First, create a data file with an arbitrary name such as myfile: 
25 3456-89 


Then use the PINC command in the pin pulldown menu to connect the in- 
put file to the INT2 pin. 


pinc myfile, int2 Connects your data file 
to the specific interrupt pin 


This command connects myfile to the INT2 pin. As a result, the simulator 
generates an INT2 external interrupt at the 12th, 34th, 56th, and 89th clock 
cycles. 


pinl 


pind 


Simulating External Interrupts (Simulator Only) 


To verify that your input file is connected to the correct pin, use the PINL 
command. The syntax for this command is: 


pinl 
(_] The pinname identifies the devices’ input pin. It must be one of the simu- 
lated pin names (INT1—INT4) or the BIO pin name. 


The PINL command displays all of the unconnected pins first, followed by the 
connected pins. For a pin that has been connected, it displays the name of the 
pin and the absolute pathname of the file in the COMMAND window. 


-— COMMAND 
PIN FILENAME 

INT1 NULL 

INT3 NULL 

INT4 NULL 

BIO NULL 
= INT?) /320h11/myfile 
>>> 


To end the interrupt simulation, disconnect the pin. You can do this with the 
following command: 


pind pinname 


The pinname parameter identifies the interrupt pin and must be one of the ex- 
ternal interrupt pins (INT1—-INT4) or the BIO pin. The PIND command de- 
taches the file from the input pin. After executing this command, you can con- 
nect another file to the same pin. 
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Chapter 7 


Loading, Displaying, and 
Running Code 


The main purpose of a debugging system is to allow you to load and run your 
programs in a test environment. This chapter tells you how to load your pro- 
grams into the debugging environment, run them on the target system, and 
view the associated source code. Many of the commands described in this 
chapter can also be executed from the Load pulldown menu. 


Topic Page 
7.1. Code-Display Windows: 7-2 
Viewing Assembly Language Code, C Code, or Both 
Selecting a debugging mode 7-3 
7.2 Displaying Your Source Programs (or Other Text Files) 7-4 
Displaying assembly language code 7-4 
Modifying assembly language code 7-5 
Additional information about modifying assembly language code 7-7 
Displaying C code 7-8 
Displaying other text files IS) 
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Loading code while invoking the debugger 7-10 
Loading code after invoking the debugger 7-10 
7.4 Where the Debugger Looks for Source Files 7-11 
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Defining the starting point for program execution TAZ 
Running code Halls 
Single-stepping through code 7-14 
Running code while disconnected from the target system 7-16 
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7.7 Benchmarking 7-19 
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7.1 Code-Display Windows: 
Viewing Assembly Language Code, C Code, or Both 


The debugger has three code-display windows: 


[_.] The DISASSEMBLY window displays the reverse assembly of program 
memory contents. 


|_| The FILE window displays any text file; its main purpose is to display C 
source files. 


|_| The CALLS window identifies the current function (when C code is run- 
ning). 


You can view code in several different ways. The debugger has three different 
code displays that are associated with the three debugging modes. The de- 
bugger’s selection of the appropriate display is based on two factors: 


[_]} The mode you select, and 


[_] Whether your program is currently executing assembly language code or 
C code. 


Here’s asummary of the modes and displays; for a complete description of the 
three debugging modes, refer to Section 4.1, Debugging Modes and Default 
Displays (page 4-2). 


The debugger uses these 
Use this mode _— To view code-display windows 


assembly mode assembly language code only (1 DISASSEMBLY 
(even if your program is 
executing C code) 

auto mode assembly language code 1) DISASSEMBLY 


(when that’s what your 
program is running) 


auto mode C code only O FILE 
(when that’s what your O CALLS 
program is running) 

mixed mode both assembly language and © DISASSEMBLY 
C code O FILE 


O CALLS 


You can switch freely between the modes. If you choose auto mode, then the 
debugger displays C code or assembly language code, depending on the type 
of code that is currently executing. 
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Selecting a debugging mode 


UU 


When you first invoke the debugger, it automatically comes up in auto mode. 
You can then choose assembly or mixed mode. There are several ways to do 
this. 


The Mode pulldown menu provides an easy method for 
switching modes. There are several ways to use the 
pulldown menus; here’s one method: 


(auto) 


Asm 
Mixed 


1) Point to the menu name. 


2) Press the left mouse button; do not release the button. Move the mouse 
down the menu until your choice is highlighted. 


3) Release the mouse button. 


For more information about the pulldown menus, refer to Section 5.2, Using 
the Pulldown Menus, on page 5-7. 


Pressing this key causes the debugger to switch modes in this order: 


(~ auto —H-W--+ assembly ————+ ™) 


Enter any of these commands to switch to the desired debugging mode: 
Changes from the current mode to auto mode. 

Changes from the current mode to assembly mode. 

Changes from the current mode to mixed mode. 


If the debugger is already in the desired mode when you enter a mode com- 
mand, then the command has no effect. 
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7.2 Displaying Your Source Programs (or Other Text Files) 


The debugger displays two types of code: 


auto, assembly, or mixed mode. 


[_] It displays assembly language code in the DISASSEMBLY window in 


[_] It displays C code in the FILE window in auto and mixed modes. 


The DISASSEMBLY and FILE windows are primarily intended for displaying 
code that the PC points to. By default, the FILE window displays the C source 
for the current function (if any), and the DISASSEMBLY window shows the cur- 


rent disassembly. 


Sometimes it’s useful to display other files or different parts of the same file; 
for example, you may want to set a breakpoint at an undisplayed line. The 
DISASSEMBLY and FILE windows are not large enough to show the entire 
contents of most assembly language and C files, but you can scroll through 
the windows. You can also tell the debugger to display specific portions of the 


disassembly or C source. 


Displaying assembly language code 


The assembly language code in the DISASSEMBLY window is the reverse 
assembly of program-memory contents. (This code doesn’t come from any of 
your text files or from the intermediate assembly files produced by the 


compiler.) 


MEMORY [PROG] 
0118 7802 


0119 bf£80 
Ola 017c 
8bb8 
a6a0 
b801 


addresses contents of disassembly of object 


program memory code in memory 


(object code) 
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dasm 


or 


addr 


or 
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When you invoke the debugger, it comes up in auto mode. If you load an object 
file when you invoke the debugger, then the DISASSEMBLY window displays 
the reverse assembly of the object file that’s loaded into memory. If you don’t 
load an object file, the DISASSEMBLY window shows the reverse assembly 
of whatever happens to be in memory. 


In assembly and mixed modes, you can use these commands to display a 
different portion of code in the DISASSEMBLY window. 


Use the DASM command to display code beginning at a specific point. The 
syntax for this command is: 


dasm_ address 
dasm_ function name 


This command modifies the display so that address or function name is 
displayed within the DISASSEMBLY window. The debugger continues to dis- 
play this portion of the code until you run a program and halt it. 


Use the ADDR command to display assembly language code beginning at a 
specific point. The syntax for this command is: 


addr address 
addr function name 


In assembly mode, ADDR works like the DASM command, positioning the 
code starting at address or at function name as the first line of code in the 
DISASSEMBLY window. In mixed mode, ADDR affects both the 
DISASSEMBLY and FILE windows. 


Modifying assembly language code 


<a 


You can modify the code in the disassembly window on a statement-by-state- 
ment basis. The method for doing this is called patch assembly. Patch 
assembly provides a simple way to temporarily correct minor problems by 
allowing you to change individual statements and instruction words. 


Note that you can’t use the patch assembly feature if you’re running the debug- 
ger under DOS. 


Use the PATCH command to identify the address of the statement you want 
to change and the new statement you want to use at that address. The format 
for this command is: 


patch address, assembly language statement 
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OK 


For patch assembly, use the right mouse button instead of the left. (Clicking 
the left mouse button sets a software breakpoint.) 


1) 


2) 


Point to the statement that you want to modify. 


Click the right button. The debugger will open a dialog box so that you can 
enter the new statement. The address field will already be filled in; clicking 
on the statement defines the address. The statement field will already be 
filled in with the current statement at that address (this is useful when only 
minor edits are necessary). 


Patch assembly may, at times, cause undesirable side effects: 


(_] Patching amultiple-word instruction with an instruction of lesser length will 


leave “garbage” or an unwanted new instruction in the remaining old in- 
struction fragment. This fragment must be patched with either a valid in- 
struction or a NOP, or else unpredictable results may occur when running 
code. 


Substituting a larger instruction for a smaller one will partially or entirely 
overwrite the following instruction; you will lose the instruction and may be 
left with another fragment. 


If you want to insert a large amount of new code or if you want to skip over a 
section of code, you can use a different patch assembly technique: 


_] To insert a large section of new code, patch a branch instruction to go to 


an area of memory not currently in use. Using the patch assembler, add 
new code to this area of memory and branch back to the statement follow- 
ing the initial branch. 


To skip over a portion of code, patch a branch instruction to go beyond that 
section of code. 


The patch assembler changes only the disassembled assembly 
language code—it does not change your source code. After 
determining the correct solution to problems in the disassembly, edit 


your source file, recompile or reassemble it, and reload the new 
object file into the debugger. 
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Additional information about modifying assembly language code 


When using patch assembly to modify code in the disassembly window, keep 
these things in mind: 


LL} 
L} 


Directives. You cannot use directives (such as .global or .word). 


Expressions. You can use constants, but you cannot use arithmetic 
expressions. For example, an expression like 12 + 33 is not valid in patch 
assembly, but a constant such as 12 is allowed. 


Labels. You cannot define labels. For example, a statement such as the 
following is not allowed: 


LOOP: B LOOP 


However, an instruction can refer to a label, as long as it is defined in a 
COFF file that is already loaded. 


Constants. You can use hexadecimal, octal, decimal, and binary 
constants. The syntax to input constants is the same as that for the DSP 
assembler. (Refer to the TMS320 Fixed-Point DSP Assembly Language 
Tools User's Guide.) 


Error messages. The error messages for the patch assembler are the 
same as the corresponding DSP assembler error messages. Refer to the 
TMS320 Fixed-Point DSP Assembly Language Tools User’s Guide for a 
detailed list of these messages. 
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Displaying C code 
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file 


func 


or 


Unlike assembly language code, C code isn’t reconstructed from memory 
contents—the C code that you view is your original C source. You can display 
C code explicitly or implicitly: 


[_.] You can force the debugger to show C source by entering a FILE, FUNC, 
or ADDR command. 


[_} In auto and mixed modes, the debugger automatically opens a FILE 
window if you’re currently running C code. 


These commands are valid in C and mixed modes: 


Use the FILE command to display the contents of any text file. The syntax for 
this command is: 


file filename 


This uses the FILE window to display the contents of filename. The debugger 
continues to display this file until you run a program and halt in a C function. 
Although this command is most useful for viewing C code, you can use the 
FILE command for displaying any text file. You can view only one text file at 
atime. Note that you can also access this command from the Load pulldown 
menu. 


(Displaying a file doesnt load that file’s object code. If you want to be able to 
run the program, you must load the file’s associated object code as described 
in Section 7.3 on page 7-10.) 


Use the FUNC command to display a specific C function. The syntax for this 
command is: 


fune function name 
func address 


FUNC modifies the display so that function name or address is displayed with- 
in the window. If you supply an address instead of a function name, the FILE 
window displays the function containing address and places the cursor at that 
line. 


Note that FUNC works similarly to FILE, but you don’t need to identify the name 
of the file that contains the function. 


addr 


HW 


or 
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Use the ADDRcommand to display C or assembly code beginning at a specific 
point. The syntax for this command is: 


addr address 
addr function name 


In a C display, ADDR works like the FUNC command, positioning the code 
starting at address or at function name as the first line of code in the FILE 
window. In mixed mode, ADDR affects both the FILE and DISASSEMBLY 
windows. 


Whenever the CALLS window is open, you can use the mouse or function keys 
to display a specific C function. This is similar to the FUNC or ADDR command 
but applies only to the functions listed in the CALLS window. 


1) Inthe CALLS window, point to the name of the C function. 


2) Click the left mouse button. 


(If the CALLS window is active, you can also use the arrow keys and to 
display the function; see the CALLS window discussion on page 4-9 for 
details.) 


Displaying other text files 


The DISASSEMBLY window always displays the reverse assembly of memory 
contents, no matter what is in memory. 


The FILE window is primarily for displaying C code, but you can use the FILE 
command to display any text file within the FILE window. You may, for example, 
wish to examine system files such as autoexec.bat or an initialization batch file. 
You can also view your original assembly language source files in the FILE 
window. 


You are restricted to displaying files that are 65,518 bytes long or less. 
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7.3 Loading Object Code 


In order to debug a program, you must load the program’s object code into 
memory. You can do this as you’re invoking the debugger, or you can do it after 
you've invoked the debugger. (Note that you create an object file by compiling, 
assembling, and linking your source files; see Section 1.6, Preparing Your 
Program for Debugging, on page 1-12.) 


Loading code while invoking the debugger 


You can load an object file when you invoke the debugger (this has the same 
effect as using the debugger’s LOAD command). To do this, enter the appro- 
priate debugger-invocation command along with the name of the object file. 


If you want to load a file’s symbol table only, use the —s option (this has the 
same effect as using the debugger’s SLOAD commana). To do this, enter the 
appropriate debugger-invocation command along with the name of the object 
file and specify —s. 


Loading code after invoking the debugger 
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load 


reload 


sload 


After you invoke the debugger, you can use one of three commands to load 
object code and/or the symbol table associated with an object file. Use these 
commands as described below, or use them from the Load pulldown menu. 


Use the LOAD command to load both an object file and its associated symbol 
table. In effect, the LOAD command performs both a RELOAD and an SLOAD. 
The format for this command is: 


load object filename 
If you don’t supply an extension, the debugger will look for filename.out. 
Use the RELOAD command to load only an object file without loading its asso- 


ciated symbol table. This is useful for reloading a program when memory has 
been corrupted. The format for this command is: 


reload [object filename] 

If you enter the RELOAD command without specifying a filename, the debug- 
ger reloads the file that you loaded last. 

Use the SLOAD command to load only a symbol table. The format for this com- 
mand is: 

sload object filename 


SLOAD is useful in a debugging environment in which the debugger cannot, 
or need not, load the object code (for example, if the code is in ROM). SLOAD 
clears the existing symbol table before loading the new one but does not 
modify memory or set the program entry point. 
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7.4 Where the Debugger Looks for Source Files 


cd 


use 


Some commands (FILE, LOAD, RELOAD, and SLOAD) expect a filename as 
a parameter. If the filename includes path information, the debugger uses the 
file from the specified directory and does not search for the file in any other 
directory. If you don’t supply path information, though, the debugger must 
search for the file. The debugger first looks for these files in the current 
directory. You may, however, have your files in several different directories. 


(_] If you’re using LOAD, RELOAD, or SLOAD, you have only two choices for 
supplying the path information: 


Specify the path as part of the filename. 


Alternatively, you can use the CD command to change the current 
directory from within the debugger. The format for this command is: 


cd _ directory name 


_] If you’re using the FILE command, you have several options: 


Within the DOS environment, you can name additional directories with 
the D_SRC environment variable. The format for doing this is: 


SET D_SRC=pathname,pathname 


This allows you to name several directories that the debugger can 
search. If you use the same directories often, it may be convenient to 
set the D_SRC environment variable in your autoexec.bat or 
initdb.bat file. If you do this, then the list of directories is always avail- 
able when you're using the debugger. 


When you invoke the debugger, you can use the — i option to name 
additional source directories for the debugger to search. The format 
for this option is —i pathname. 


You can specify multiple pathnames by using several —i options (one 
pathname per option). The list of source directories that you create 
with —i options is valid until you quit the debugger. 


Within the debugger environment, you can use the USE command to 
name additional source directories. The format for this command is: 


use directory name 


You can specify only one directory at a time. 


In all cases, you can use relative pathnames such as ..\csource or ..\..\code. 
The debugger can recognize a cumulative total of 20 paths specified with 
D_SRC, -i, and USE. 
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7.5 Running Your Programs 


To debug your programs, you must execute them on one of the three 'C5x de- 
bugging tools (emulator, EVM, or simulator). The debugger provides two basic 
types of commands to help you run your code: 


[_} Basic run commands run your code without updating the display until you 
explicitly halt execution. There are several ways to halt execution: 


M@ Seta breakpoint. 

HM When you issue a run command, define a specific ending point. 
HM Press so). 

HM Press the left mouse button. 


_] Single-step commands execute assembly language or C code, one 
statement at a time, and update the display after each execution. 


Defining the starting point for program execution 
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rest 


?/eval 


All run and single-step commands begin executing from the current PC (pro- 
gram counter). When you load an object file, the PC is automatically set to the 
starting point for program execution. You can easily identify the current PC by: 
|_| Finding its entry in the CPU window 
or 
[_| Finding the appropriately highlighted line in the FILE or DISASSEMBLY 
window. To do this, execute one of these commands: 
dasm PC 
or addr PC 


Sometimes you may want to modify the PC to point to a different position in 
your program. There are two ways to do this: 


(_] If you executed some code and would like to rerun the program from the 
original program entry point, use the RESTART (REST) command. The 
format for this command is: 
restart 

or rest 
Note that you can also access this command from the Load pulldown 
menu. 

(_} You can directly modify the PC’s contents with one of these commands: 


2PC = new value 
or eval pe = new value 


After halting execution, you can continue from the current PC by reissuing any 
of the run or single-step commands. 


Running code 


: run 
i 


go 


ret 


or 


runb 
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The debugger supports several run commands. 


The RUN command is the basic command for running an entire program. The 
format for this command is: 


run [expression] 
The command's behavior depends on the type of parameter you supply: 


_] lf you don’t supply an expression, the program executes until it encounters 
a breakpoint or until you press or the left mouse button. 


_] If you supply a logical or relational expression, this becomes a conditional 
run (see page 7-17). 


__] Ifyou supply any other type of expression, the debugger treats the expres- 
sion as a count parameter. The debugger executes count instructions, 
halts, then updates the display. 


Use the GO command to execute code up to a specific point in your program. 
The format for this command is: 

go [address] 

If you don’t supply an address parameter, then GO acts like a RUN command 
without an expression parameter. 

The RETURN (RET) command executes the code in the current C function 
and halts when execution returns to its caller. The format for this command is: 


return 
ret 


Breakpoints do not affect this command, but you can halt execution by press- 
ing or the left mouse button. 


Use the RUNB (run benchmark) command to execute a specific section of 
code and count the number of clock cycles consumed by the execution. The 
format for this command is: 


runb 


Using the RUNB command to benchmark code is a multistep process, 
described in Section 7.7, Benchmarking, on page 7-19. 


Pressing this key runs code from the current PC. This is similar to entering a 
RUN command without an expression parameter. 
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Single-stepping through code 
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step 


Single-step execution is similar to running a program that has a breakpoint set 
on each line. The debugger executes one statement, updates the display, and 
halts execution. (You can supply a parameter that tells the debugger to 
single-step more than one statement; the debugger updates the display after 
each statement.) You can single-step through assembly language code or C 
code. 


The debugger supports several commands for single-stepping through a pro- 
gram. Command execution may vary, depending on whether you're 
single-stepping through C code or assembly language code. 


Note that the debugger ignores interrupts when you use the STEP command 
to single-step through assembly language code. 


Each of the single-step commands has an optional expression parameter that 
works like this: 


[__] If you don’t supply an expression, the program executes a single state- 
ment, then halts. 


_] If you supply a logical or relational expression, this becomes a conditional 
single-step execution (See page 7-17). 


|_| If you supply any other type of expression, the debugger treats the expres- 
sion as a count parameter. The debugger single-steps count C or 
assembly language statements (depending on the type of code you’re in). 


Use the STEP command to single-step through assembly language or C code. 
The format for this command is: 


step [expression] 


If you're in C code, the debugger executes one C statement at a time. In 
assembly or mixed mode, the debugger executes one assembly language 
statement at a time. 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug op- 
tion). When function execution completes, single-step execution returns to the 
caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 


cstep 


next 
cnext 
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The CSTEP command is similar to STEP, but CSTEP always single-steps in 
terms of a C statement. If you’re in C code, STEP and CSTEP behave 
identically. In assembly language code, however, CSTEP executes all assem- 
bly language statements associated with one C statement before updating the 
display. The format for this command is: 


cstep [expression] 


The NEXT and CNEXT commands are similar to the STEP and CSTEP com- 
mands. The only difference is that NEXT/CNEXT never show single-step 
execution of called functions—they always step to the next consecutive state- 
ment. The formats for these commands are: 


next [expression] 
cnext [expression] 


You can also single-step through programs by using function keys: 


Acts as a STEP command. 


Acts as a NEXT command. 


The debugger allows you to execute several single-step commands from the 
selections on the menu bar. 


To execute a STEP: 

1) Point to Step=F8 in the menu bar. 

2) Press and release the left mouse button. 
To execute a NEXT: 


1) Point to Next=F10 in the menu bar. 


2) Press and release the left mouse button. 
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Running code while disconnected from the target system 


EVM & 
emulator 
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runf 


halt 


reset 


Use the RUNF command to disconnect the emulator or EVM from the target 
system while code is executing. The format for this command is: 


runf 


When you enter RUNF, the debugger clears all breakpoints, disconnects the 
emulator or EVM from the target system, and causes the processor to begin 
execution at the current PC. You can quit the debugger, or you can continue 
to enter commands. However, any command that causes the debugger to ac- 
cess the target at this time will produce an error. 


RUMF is useful in a multiprocessor system. It’s also useful ina system in which 
several target systems share an emulator; RUNF enables you to disconnect 
the emulator from one system and connect it to another. 


Use the HALT command to halt the target system after you’ve entered a RUNF 
command. The format for this command is: 


halt 


When you invoke the debugger, it automatically executes a HALT command. 
Thus, if you enter a RUNF, quit the debugger, and later reinvoke the debugger, 
you will effectively reconnect the emulator to the target system and run the 
debugger in its normal mode of operation. When you invoke the debugger, use 
the —s option to preserve the current PC and memory contents. 


The RESET command resets the target system. This is a software reset. The 
format for this command is: 


reset 


If you are using the simulator and execute the RESET commana, the simulator 
simulates the ’C5x processor and peripheral reset operation, putting the pro- 
cessor in a known state. 
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Running code conditionally 


The RUN, STEP, CSTEP, NEXT, and CNEXT commands all have an optional 
expression parameter that can be a relational or logical expression. This type 
of expression has one of the following operators as the highest precedence 
operator in the expression: 


Vv 
— il Vv 
ll 


When you use this type of expression with these commands, the command 
becomes a conditional run. The debugger executes the command repeatedly 
for as long as the expression evaluates to true. 


You must use software breakpoints with conditional runs; the expression is 
evaluated each time the debugger encounters a breakpoint. Each time the 
debugger evaluates the conditional expression, it updates the screen. The 
debugger applies this algorithm: 


top: 
if (expression = = 0) go to end; 
run or single-step (until breakpoint, Sc) , or mouse button halts execution) 
if (halted by breakpoint, not by or mouse button) go to top 

end: 


Generally, you should set the breakpoints on statements that are related in 
some way to the expression. For example, if you’re watching a particular 
variable in a WATCH window, you may want to set breakpoints on statements 
that affect that variable and to use that variable in the expression. 
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7.6 Halting Program Execution 
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ESC 


Whenever you’re running or single-stepping code, program execution halts 
automatically if the debugger encounters a breakpoint or if it reaches a 
particular point where you told it to stop (by supplying a count or an address). 
If you’d like to explicitly halt program execution, there are two ways to accom- 
plish this: 


Click the left mouse button. 


Press the escape key. 


After halting execution, you can continue program execution from the current 
PC by reissuing any of the run or single-step commands. 


Benchmarking 


7.7 Benchmarking 


The debugger allows you to keep track of the number of CPU clock cycles 
consumed by a particular section of code. The debugger maintains the count 
in a pseudoregister named CLK. 


Benchmarking code is a multiple-step process: 


Step 1: Setasoftware breakpoint at the statement that marks the beginning 
of the section of code you'd like to benchmark. 


Step 2: Setasoftware breakpoint at the statement that marks the end of the 
section of code you'd like to benchmark. 


Step 3: Enter any RUN command to execute code up to the first breakpoint. 


Step 4: Now enter the RUNB command: 
runb 
When the processor halts at the second breakpoint, the value of CLK is valid. 


To display it, use the ? command or enter it into the WATCH window with the 
WA command. This value is valid until you enter another RUN command. 


Note: 


[_] The RUNB command counts CPU clock cycles from the current PC to 
the breakpoint. This count is not cumulative. You cannot add the number 
of clock cycles from point A to point B to the number of cycles from point 
B to point C to learn the number of cycles from point A to point C. This 
error occurs because of pipeline filling and flushing. 


(_] The value in CLK is valid only after you use a RUNB command that is 
terminated by a software breakpoint. 
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Chapter 8 


Managing Data 


The debugger allows you to examine and modify many different types of data 
related to the ’C5x and to your program. You can display and modify the values 
of: 

[__] Individual memory locations or a range of memory 

[__] ‘C5x registers 

[__] Variables, including scalar types (ints, chars, etc.) and aggregate types 

(arrays, structures, etc.) 
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Where Data Is Displayed / Basic Commands for Managing Data 


8.1 Where Data Is Displayed 


Four windows are dedicated to displaying the various types of data. 


Type of data 


memory locations 


register values 


pointer data or selected variables of 


an aggregate type 


selected variables (scalar types or 
individual members of aggregate 
types) and specific memory loca- 


tions or registers 


8.2 Basic Commands for Managing Data 


x 
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whatis symbol 


Command 
whatis giant 


whatis xxx 


Window name and purpose 


MEMORY windows 

Display the contents of a range of data 
memory, program memory, or I/O space 
CPU window 

Displays the contents of ’C5x registers 
DISP windows 

Display the contents of aggregate types 
and show the values of individual 
members 

WATCH window 

Displays selected data 


This group of windows is referred to as data-display windows. 


The debugger provides special-purpose commands for displaying and modify- 
ing data in dedicated windows. The debugger also supports several general- 
purpose commands that you can use to display or modify any type of data. 


whatis If you want to know the type of a variable, use the WHATIS command. The 
syntax for this command is: 


This lists symbol’s data type in the COMMAND window display area. The 
symbolcan be any variable (local, global, or static), a function name, structure 
tag, typedef name, or enumeration constant. 


Result displayed in the COMMAND window 


struct 


struct 
int 
int 
int 
int 
int 


zzz giant[100]; 


XXX { 


fal. 2e 
f2 : 4; 


iv 
struct xxx *£3; 


int 


£4[10]; 


eval 
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The ? (evaluate expression) command evaluates an expression and shows 
the result in the COMMAND window display area. The syntax for this com- 
mand is: 


2 expression 


The expression can be any C expression, including an expression with side 
effects. However, you cannot use a string constant or function call in the 
expression. 


If the result of expression is scalar, then the debugger displays the result as 
a decimal value in the COMMAND window. If expressionis a structure or array, 
? displays the entire contents of the structure or array; youcan halt long listings 
by pressing (Esc). 


Here are some examples that use the ? command. 


Command Result displayed in the COMMAND window 


? giant giant [0].b1 436547877 
giant [0].b2 -—791051538 
giant [0].b3 1952557575 
giant [0].b4 -1555212096 


etc. 
ey 4194425 
? j=0x5a 90 


Note that the DISP command (described in detail on page 8-14) behaves like 
the ? command when its expression parameter does not identify an aggregate 
type. 


The EVAL (evaluate expression) command behaves like the ? command but 
does not show the result in the COMMAND window display area. The syntax 
for this command is: 


eval expression 
e expression 


EVAL is useful for assigning values to registers or memory locations in a batch 
file (where it’s not necessary to display the result). 


For information about the PDM version of the EVAL command, refer to Section 
2.9, page 2-21. 
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8.3 Basic Methods for Changing Data Values 


The debugger provides you with a great deal of flexibility in modifying various 
types of data. You can use the debugger’s overwrite editing capability, which 
allows you to change a value simply by typing over its displayed value. You can 
also use the data-management commands for more complex editing. 


Editing data displayed in a window 


ESC 
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Use overwrite editing to modify data in a data-display window; you can edit: 


[_] Registers displayed in the CPU window 

[_] Memory contents displayed ina MEMORY window 
[_| Elements displayed in a DISP window 

[_| Values displayed in the WATCH window 


There are two similar methods for overwriting displayed data: 


This method is sometimes referred to as the “click and type” method. 


1) Point to the data item that you want to modify. 


2) Click the left button. The debugger highlights the selected field. (Note that 
the window containing this field becomes active when you press the 
mouse button.) 


3) Type the new information. If you make a mistake or change your mind, 
press or move the mouse outside the field and press/release the left 
button; this resets the field to its original value. 


4) When you finish typing the new information, press or any arrow key. 
This replaces the original value with the new value. 


1) Select the window that contains the field you’d like to modify; make this the 
active window. (Use the mouse, the WIN command, or (6). For more 
detail, see Section 4.4, The Active Window, on page 4-19.) 


2) Use arrow keys to move the cursor to the field you'd like to edit. 
Moves up 1 field at a time. 

Moves down 1 field at a time. 

Moves left 1 field at a time. 


UNHBB 


Moves right 1 field at a time. 
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(F9) 3) When the field you’d like to edit is highlighted, press ). The debugger 
highlights the field that the cursor is pointing to. 


ESC 4) Type the new information. If you make a mistake or change your mind, 
press (Esc) ; this resets the field to its original value. 


e) 5) When you finish typing the new information, press or any arrow key. 
This replaces the original value with the new value. 


Advanced “editing”—using expressions with side effects 


Using the overwrite editing feature to modify data is straightforward. However, 
data-management methods take advantage of the fact that C expressions are 
accepted as parameters by most debugger commands and that C expressions 
can have side effects. When an expression has a side effect, it means that the 
value of some variable in the expression changes as the result of evaluating 
the expression. 


This means that you can coerce many commands into changing values for 
you. Specifically, it’s most helpful to use ? and EVAL to change data as well 
as display it. 

For example, if you want to see what's in auxiliary register AR3, you can enter: 
? AR3 


You can also use this type of command to modify AR3’s contents. Here are 
some examples of how you might do this: 


? AR3++ Side effect: increments the contents of AR3 by 1 
eval --AR3 Side effect: decrements the contents of AR3 by 1 
? AR3 = 8 Side effect: sets AR3 to 8 
eval AR3/=2 Side effect: divides contents of AR3 by 2 


Note that not all expressions have side effects. For example, if you enter 
2? AR3+4, the debugger displays the result of adding 4 to the contents of AR3 
but does not modify AR3’s contents. Expressions that have side effects must 
contain an assignment operator or an operator that implies an assignment. 
Operators that can cause a side effect are: 


= += -_—= *e /= 
%= &= A= = <<c= 
>>= ++ == 
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8.4 Managing Data in Memory 


In mixed and assembly modes, the debugger maintains a MEMORY window 
that displays the contents of memory. For details concerning the MEMORY 
window, see the MEMORY windows discussion (page 4-12). 


‘MEMORY 
0000 0007 0007 0007 0007 bfff £f£f00 
0007 0008 0000 bfff 0000 0000 0001 
addresses 000e 0001 bfff 0000 O9f5 dffd ffff data 
0015 O09c6 bfff bfff f£F7Fff 0000 bfft 
001c bfff bfff £f£77 bfff 0000 0000 
0023 0900 £ff4d fffF 0000 O000 £ffft 


The debugger has commands that show the memory values at a specific 
location or that display a different range of memory in the MEMORY window. 
The debugger allows you to change the values at individual locations; refer to 
Section 8.3 (page 8-4) for more information. 


Displaying memory contents 
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The main way to observe memory contents is to view the display in a 
MEMORY window. Four MEMORY windows are available: the default window 
is labeled MEMORY, and the three additional windows are called MEMORY 1, 
MEMORY2, and MEMORY3. Notice that the default window does not have an 
extension number in its name; this is because MEMORY1, MEMORY2, and 
MEMORY%3 are pop-up windows that can be opened and closed throughout 
your debugging session. Having four windows allows you to view four different 
memory ranges. 


The amount of memory that you can display is limited by the size of the individ- 
ual MEMORY windows (which is limited only by the screen size). During a de- 
bugging session, you may need to display different areas of memory within a 
window. You can do this by typing a command or using the mouse. 


, mem 
nM 
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If you want to display a different memory range in the MEMORY window, use 
the MEM command. The basic syntax for this command is: 


mem expression 


To view different memory locations in an additional MEMORY window, use the 
MEM command with the appropriate extension number on the end. For exam- 
ple: 


To do this. . . Enter this. . . 


View the block of memory starting at address 0x8000 mem1 0x8000 
in the MEMORY1 window 


View the same block of memory (starting at address mem2 0x8000 
0x8000) but in the MEMORY2 window 


SS —— ———————————— Saad 


Note: 


If you want to view a different block of memory explicitly in the default 
MEMORY window, you can use the aliased command, MEMO. This works 
exactly the same as the MEM command. To use this command, enter: 
mem0 address 


eee sss) 


For more information, see the MEMORY windows discussion on page 4-12. 


The expression you type in represents the address of the first entry in the 
MEMORY window. The end of the range is defined by the size of the window: 
to show more memory locations, make the window larger; to show fewer loca- 
tions, make the window smaller. (See Resizing a window, page 4-21, for more 
information.) 


Expressioncan be an absolute address, a symbolic address, or any C expres- 
sion. Here are several examples: 


[_} Absolute address. Suppose that you want to display data memory begin- 
ning from the very first address. You might enter this command: 
mem 0x00 
Hint: MEMORY window addresses are shown in hexadecimal format. If 


you want to specify a hex address, be sure to prefix the address number 
with 0x; otherwise, the debugger treats the number as a decimal address. 


(_} Symbolic address. You can use any defined C symbol as an expression 
parameter. For example, if your program defined a symbol named SYM, 
you could enter this command: 
meml &SYM 


Hint: Prefix the symbol with the & operator to use the address of the 
symbol. 
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[_} C expression. If you use a C expression as a parameter, the debugger 
evaluates the expression and uses the result as a memory address: 


mem SP —- ARO + label 


You can also change the display of any data-display window—including the 
MEMORY window—by scrolling through the window’s contents. See the 
Scrolling through a window's contents discussion (page 4-26) for more details. 


Displaying program memory and I/O space 
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By default, the MEMORY windows display data memory, but you can also 
display program memory or I/O space. To display program memory, follow any 
address parameter with @prog. If you are using an emulator or EVM you can 
display I/O space; add @io following an address parameter. For example, you 
can follow the MEM command's expression parameter with @prog. This suffix 
tells the debugger that the expression parameter identifies a program memory 
address instead of a data memory address. 


If you display either program memory or I/O space in the MEMORY window, 
the debugger changes the window’s label to MEMORY [PROG] or 
MEMORY [IO] so that there is no confusion about what type of memory is dis- 
played at any given time. 


Any of the examples presented in this section could be modified to display 
program memory or I/O space: 


mem 0x00@io 

mem &SYM@prog 

mem (SP — ARO + label) @prog 
2? *0x26@io 

wa *0x26@prog 

disp *(float *)0x26@io 


You can also use the suffix @data to display data memory; however, since 
data memory is the default, the @data suffix is unnecessary. 
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Displaying memory contents while you’re debugging C 


If you’re debugging C code in auto mode, you won’t see a MEMORY window— 
the debugger doesn’t show the MEMORY window in the C-only display. 
However, there are several ways to display memory in this situation. 


Hint: If you want to use the contents of an address as a parameter, be sure 
to prefix the address with the C indirection operator (*). 


(_] If you have only a temporary interest in the contents of a specific memory 
location, you can use the ? command to display the value at this address. 
For example, if you want to know the contents of data memory location 26 
(hex), you could enter: 


? *0x26 
The debugger displays the memory value in the COMMAND window 
display area. 


(_] If you want the opportunity to observe a specific memory location over a 
longer period of time, you can display it ina WATCH window. Use the WA 
command to do this: 


wa *0x26 
[_} You can also use the DISP command to display memory contents. The 
DISP window shows memory in an array format with the specified address 


as “member” [0]. In this situation, you can also use casting to display 
memory contents in a different numeric format: 


disp *(float *) 0x26 
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Saving memory values to a file 


mn 
eS 


Sometimes it’s useful to save a block of memory values to a file. You can use 
the MS (memory save) command to do this; the files are saved in COFF for- 
mat. The syntax for the MS command is: 


ms_ address, page, length, filename 


[| The address parameter identifies the first address in the block. 


[__] The page is a one-digit number that identifies the type of memory (pro- 
gram, data, or I/O) to save: 


To save this type of Use this value as the page 
memory parameter 

Program memory 0 

Data memory 1 

I/O space 2 (EVM and Emulator) 


[_] The length parameter defines the length, in words, of the block. This 
parameter can be any C expression. 


[__] The filename is a system file. If you don’t supply an extension, the debug- 
ger adds an .obj extension. 


For example, to save the values in data memory locations 0x0000 — 0x0010 
to a file named memsave, you could enter: 


ms 0x0,1,0x10,memsave 


To reload memory values that were saved in a file, use the LOAD command. 
For example, to reload the values that were stored in memsave, enter: 


load memsave.obj 
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Filling a block of memory 


Sometimes it’s useful to be able to fill an entire block of memory at once. You 
can do this by using the FILL command. The syntax for this command is: 


fill address, page, length, data 


[_] The address parameter identifies the first address in the block. 


|] The page is a one-digit number that identifies the type of memory (pro- 
gram or data) to fill: 


To fill this type of Use this value as the page 
memory parameter 

Program memory 0 

Data memory 1 

I/O space 2 (EVM and Emulator Only) 


[__] The /ength parameter defines the number of words to fill. 


_] The data parameter is the value that is placed in each word in the block. 


For example, to fill program memory locations 0x1 0FF—0x110D with the value 
OxABCD, you would enter: 


fill Ox10ff,0,0xf, Oxabcd 
If you want to check whether memory has been filled correctly, you can enter: 
mem 0x10ff@prog 


This changes the MEMORY window display to show the block of memory 
beginning at program memory address 0x10FF. 


Note that the FILL command can also be executed from the Memory pulldown 
menu. 
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8.5 Managing Register Data 


In mixed and assembly modes, the debugger maintains a CPU window that 
displays the contents of individual registers. For details concerning the CPU 
window, see the CPU window discussion (page 4-15). 


00000000 A 


0000 AR1 o95£ 
09c6 
8ffic 
0000 
0002 


v 
0000 
0000 | 


The debugger provides commands that allow you to display and modify the 
contents of specific registers. You can use the data-management commands 
or the debugger’s overwrite editing capability to modify the contents of any reg- 
ister displayed in the CPU or WATCH window. Refer to Section 8.3, Basic 
Methods for Changing Data Values (page 8-4), for more information. 


ACC 00000002 ACCB ffffffff 
TOS £050 ARO 
AR3 frcr AR4 
AR7 bfff sto 
£f4d IMR 
Spee s 
0002 
3fff 


register 
name 


register 
contents 


Displaying register contents 


The main way to observe register contents is to view the display in the CPU 
window. However, you may not be interested in all of the registers; if you're in- 
terested in only afew registers, you might want to make the CPU window small 
and use the extra screen space for the DISASSEMBLY or FILE display. In this 
type of situation, there are several ways to observe the contents of the selected 
registers. 


_] Ifyou have only a temporary interest in the contents of a register, you can 
use the ? command to display the register’s contents. For example, if you 
want to know the contents of ARO, you could enter: 

? ARO 
The debugger displays ARO’s current contents in the COMMAND window 
display area. 


_] If you want to observe a register over a longer period of time, you can use 
the WA command to display the register in a WATCH window. For 
example, if you want to observe the status register, you could enter: 
wa STO,Status Register 0 
This adds the STO to the WATCH window and labels it as Status Register 


0. The register’s contents are continuously updated, just as if you were ob- 
serving the register in the CPU window. 


When you're debugging C in auto mode, these methods are also useful 
because the debugger doesn’t show the CPU window in the C-only display. 
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Accessing the hardware stacks (simulator only) 


The simulator provides access to the eight-level hardware stack, which is used 
for saving the PC value during interrupts and subroutines. The pseudoregister 
symbols STKO—STK7 represent hardware stack levels 0-7, respectively. You 
can view the contents of these stack levels by adding the appropriate STK 
symbol to the WATCH window. For example, to watch hardware stack level 0, 
enter: 


wa STKO 


8.6 Managing Data in a DISP (Display) Window 


The main purpose of the DISP window is to display members of complex, 
aggregate data types such as arrays and structures. The debugger shows 
DISP windows only when you specifically request to see DISP windows with 
the DISP command (described below). Note that you can have up to 120 DISP 
windows open at once. For additional details about DISP windows, see the 
DISP window discussion (page 4-16). 


--DISP: str ———H_——_,, 


a 84 A 
b 86 
structure —+< 172 
members £1 --DISP: str. £4 ——W——_, 
POR [0] 44276127 4 
v [1] 1778712578 
£3 0x18740001 
member OA feat | [2] 555492660 


values [3] 356713217 
en 138412802 
[5] 182452229 
[6] 35659888 
This member is an array, and [7] 37749506 
you can display its contents in [8] 134742016 i 
a second DISP window [9] 138412801 _| 


Remember, you can use the data-management commands or the debugger’s 
overwrite editing capability to modify the contents of any value displayed ina 
DISP window. Refer to Section 8.3, Basic Methods for Changing Data Values 
(page 8-4), for more information. 
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Displaying data in a DISP window 


eS 


To open a DISP window, use the DISP command. Its basic syntax is: 
disp expression 


If the expression is not an array, structure, or pointer (of the form *pointer 
name), the DISP command behaves like the ? command. However, if expres- 
sion is one of these types, the debugger opens a DISP window to display the 
values of the members. 


If a DISP window contains a long list of members, you can use (PAGEDOWN), 
, or arrow keys to scroll through the window. If the window contains an 
array of structures, you Can use (CONTROL) (PAGE DOWN) and to 
scroll through the array. 


Once you open a DISP window, you may find that a displayed member is 
another one of these types. This is how you identify the members that are 
arrays, structures, or pointers: 


A member that is an array looks like this [.. .] 
A member that is a structure looks like this {is gat 
A member that is a pointer looks like an address 0x0000 


You can display the additional data (the data pointed to or the members of the 
array or structure) in additional DISP windows (these are referred to as 
children). There are three ways to do this. 


Use the DISP command again; this time, expression must identify the member 
that has additional data. For example, if the first expression identifies a struc- 
ture named strand one of str’s members is an array named f4, you can display 
the contents of the array by entering this command: 


disp str.f4 


This opens a new DISP window that shows the contents of the array. If str has 
a member named 73 that is a pointer, you could enter: 


disp *str.£3 


This opens a window to display what str.f3 points to. 


Managing Data in a DISP (Display) Window 


Here’s another method of displaying the additional data: 


1) Point to the member in the DISP window. 


2) Now click the left button. 


Ikey| Here’s the third method: 
( @® 1) Usethe arrowkeys to move the cursor up and down in the list of members. 
2) When the cursor is on the desired field, press 3). 
When the debugger opens a second DISP window, the new window may at 
first be displayed on top of the original DISP window; if so, you can move the 
windows so that you can see both at once. If the new windows also have 
members that are pointers or aggregate types, you can continue to open new 
DISP windows. 
Closing a DISP window 


Closing a DISP window is a simple, two-step process. 


Step 1: Make the DISP window that you want to close active (see Section 
4.4, The Active Window, on page 4-19). 


Step 2: Press €4). 
Note that you can close a window and all of its children by closing the original 
window. 


cca | 
Note: 


The debugger automatically closes any DISP windows when you execute a 
LOAD or SLOAD command. 


| | 
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8.7 Managing Data in a WATCH Window 


The debugger doesn’t maintain a dedicated window that tells you about the 
status of all the symbols defined in your program. Such a window might be so 
large that it wouldn’t be useful. Instead, the debugger allows you to create a 
WATCH window that shows you how program execution affects specific 
expressions, variables, registers, or memory locations. 


‘WATCH 


watch index———___"{[">_ 11: aro 0x1802 . 
Pag X+X 4 Vv 
S18 of ~~ | 

label current value 


The debugger displays a WATCH window only when you specifically request 
a WATCH window with the WA command (described below). Note that there 
is only one WATCH window. For additional details concerning the WATCH 
window, see the WATCH window discussion (page 4-17). 


Remember, you can use the data-management commands or the debugger’s 
overwrite editing capability to modify the contents of any value displayed in the 
WATCH window. Refer to Section 8.3, Basic Methods for Changing Data 
Values (page 8-4), for more information. 


EE | 
Note: 


All of the watch commands described can also be accessed Watch 
from the Watch pulldown menu. For more information about ace 
using the the pulldown menus, refer to Section 5.2, Using the eee 
Menu Bar and the Pulldown Menus (page 5-7). 


Displaying data in the WATCH window 


The debugger has one command for adding items to the WATCH window. 


wa To open the WATCH window, use the WA (watch add) command. The basic 
<a 


syntax is: 
wa expression [, label 


When you first execute WA, the debugger opens the WATCH window. After 
that, executing WA adds additional values to the WATCH window. 


Managing Data in a WATCH Window 


[_} The expression parameter can be any C expression, including an expres- 
sion that has side effects. It’s most useful to watch an expression whose 
value will change over time; constant expressions provide no useful func- 
tion in the WATCH window. 


(_] If you want to use the contents of an address as a parameter, be sure to 
prefix the address with the C indirection operator (*). Use the WA com- 
mand to do this: 


wa *0x26 
(_] The /abe/ parameter is optional. When used, it provides a label for the 


watched eniry. If you don’t use a /abel, the debugger displays the expres- 
sion in the label field. 


Deleting watched values and closing the WATCH window 


on 


wd 


The debugger supports two commands for deleting items from the WATCH 
window. 


If you'd like to close the WATCH window and delete all of the items in a single 
step, use the WR (watch reset) command. The syntax is: 


wr 


If you'd like to delete a specific item from the WATCH window, use the WD 
(watch delete) command. The syntax is: 


wd_ index number 


Whenever you add an item to the WATCH window, the debugger assigns it an 
index number. (The illustration of the WATCH window on page 8-16 points to 
these watch indexes.) The WD command's index number parameter must cor- 
respond to one of the watch indexes in the WATCH window. 


Note that deleting an item (depending on where it is in the list) causes the 
remaining index numbers to be reassigned. Deleting the last remaining item 
in the WATCH window closes the WATCH window. 


ae 


Note: 
The debugger automatically closes the WATCH window when you execute 
a LOAD or SLOAD command. 


eee ss) 
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8.8 Managing Pipeline Information (Simulator Only) 


The simulator supports additional features that allow you to monitor the pipe- 
line. The simulator supports pseudoregisters that you can query with ? or DISP 
or add to the WATCH window. 


Monitoring the pipeline 


The instruction pipeline consists of four phases: instruction fetch, decode, 
operand fetch, and execution. During any cycle, one to four instructions can 
be active, each at a different stage of completion. Instruction operation occurs 
during the appropriate stages of the pipeline. For example, ARAU updates of 
auxiliary registers occur during the decode phase. 


The simulator provides eight pseudoregisters that display the opcode or 
address of the instructions in each phase of the pipeline. Table 8—1 identifies 
these registers. 


Table 8-1. Pipeline Pseudoregisters 


Pipeline phase ~~“ Opcode pseudoregister Address pseudoregister_ 
Instruction fetch fins faddr 

Decode dins daddr 

Operand fetch rins raddr 

Execution xins xaddr 


For example, if you wanted to observe the decode phase during program ex- 
ecution, you could watch the dins and daddr pseudoregisters in the WATCH 
window: 


wa dins, Decode-—Opcode 
wa daddr,Decode-Address 


This adds dins and dadadr to the WATCH window and labels them as Decode- 
Opcode and Decode-Address, respectively. 


Displaying Data in Alternative Formats 


8.9 Displaying Data in Alternative Formats 


By default, all data is displayed in its natural format. This means that: 


[_] Integer values are displayed as decimal numbers. 

[_] Floating-point values are displayed in floating-point format. 

[_| Pointers are displayed as hexadecimal addresses (with a Ox prefix). 
[_] Enumerated types are displayed symbolically. 


However, any data displayed in the COMMAND, MEMORY, WATCH, or DISP 
window can be displayed in a variety of formats. 


Changing the default format for specific data types 


To display specific types of data in a different format, use the SETF command. 
The syntax for this command is: 


setf [data type, display format | 


The display format parameter identifies the new display format for any data of 
type data type. Table 8-2 lists the available formats and the corresponding 
characters that can be used as the display format parameter. 


Table 8-2. Display Formats for Debugger Data 


Display Format Parameter Display Format Parameter 
Default for the data type * Octal oO 
ASCII character (bytes) c Valid address p 
Decimal d ASCII string s 
Exponential floating point e Unsigned decimal u 
Decimal floating point f Hexadecimal X 


Table 8-3 lists the C data types that can be used for the data type parameter. 
Only a subset of the display formats applies to each data type, so Table 8-3 
also shows valid combinations of data types and display formats. 
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Table 8-3. Data Types for Displaying Debugger Data 
Valid Display Formats 


Data Type c do x ef p s_u Default Display Format 
char Vvv4 Vv ASCII (c) 

uchar Vvv4 V Decimal (d) 

short Vvv 4 V Decimal (d) 

int Vvv 4 V Decimal (d) 

uint Vv vv yv V Decimal (d) 

long Vvv 4 V Decimal (d) 

ulong Vvv 4 V Decimal (d) 

float Vv v4 Exponential floating point (e) 
double Vvovv Exponential floating point (e) 
ptr Vv Vv Address (p) 


Here are some examples: 


[__] To display all data of type short as an unsigned decimal, enter: 
setf short, u 


[__] To return all data of type short to its default display format, enter: 
setf short, * 


[(_] To list the current display formats for each data type, enter the SETF 
command with no parameters: 


setf 
You'll see a display that looks something like this: 


Display Format Defaults 
Type char: ASCII 
Type unsigned char: Decimal 
Type int: Decimal 
Type unsigned int: Decimal 
Type short: Decimal 
Type unsigned short: Decimal 
Type long: Decimal 
Type unsigned long: Decimal 
Type float: Exponential floating point 
Type double: Exponential floating point 
Type pointer: Address 


_] To reset all data types back to their default display formats, enter: 
setf * 
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Changing the default format with ?, MEM, DISP, and WA 


You can also use the ?, MEM, DISP, and WA commands to show data in alter- 
native display formats. (The ? and DISP commands can use alternative 
formats only for scalar types, arrays of scalar types, and individual members 
of aggregate types.) 


Each of these commands has an optional display format parameter that works 
in the same way as the display format parameter of the SETF command. 


When you don’t use a display format parameter, data is shown in its natural 
format (unless you have changed the format for the data type with SETF). 


Here are some examples: 


[_] To watch the PC in decimal, enter: 
wa pe,,d 


_] To display memory contents in octal, enter: 
mem 0x0,0 


(_} To display an array of integers as characters, enter: 
disp ai,c 


The valid combinations of data types and display formats listed for SETF also 
apply to the data displayed with DISP, ?, WA, and MEM. For example, if you 
want to use display format e or f, the data that you are displaying must be of 
type float or type double. Additionally, you cannot use the s display format 
parameter with the MEM command. 
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Using Software Breakpoints 


During the debugging process, you may want to halt execution temporarily so 
that you can examine the contents of selected variables, registers, and 
memory locations before continuing with program execution. You can do this 
by setting software breakpoints at critical points in your code. You can set 
software breakpoints in assembly language code and in C code. A software 
breakpoint halts any program execution, whether you're running or 
single-stepping through code. 


Software breakpoints are especially useful in combination with conditional ex- 
ecution (described on page 7-17) and benchmarking (described on page 
7-19). 


Topic Page 
9.1 Setting a Software Breakpoint 9-2 
9.2 Clearing a Software Breakpoint 9-4 
9.3 Finding the Software Breakpoints That Are Set 9-5 
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9.1 Setting a Software Breakpoint 


When you set a software breakpoint, the debugger highlights the breakpointed 
line in two ways: 


[_] It prefixes the statement with the character >. 


[_] It shows the line in a bolder or brighter font. (You can use screen-customi- 
zation commands to change this highlighting method.) 


If you set a breakpoint in the disassembly, the debugger also highlights the 
associated C statement. If you set a breakpoint in the C source, the debugger 
also highlights the associated statement in the disassembly. (If more than one 
assembly language statement is associated with a C statement, the debugger 
highlights the first of the associated assembly language statements.) 


— FILE: sample.c 1 
00044 4 
00045 > meminit () ; 
A breakpoint is setatLeeoa@—~—Ss for (i=0; i < 0x50000; i++) 
this C statement; | 90047 { v 
notice how the line is 00048 call(i); =| 
highlighted. 
A breakpoint is also 
set at the associated 
assembly language 
statement (it’s 
highlighted, too). ,)r sassemp.y 
00fc bf80 > :LACC #5555h 4 
OO0fe bf90 ADD #6666h | 
0100 bf90 ADD #777h _| 


Notes: 


[_.] After execution is halted by a breakpoint, you can continue program 
execution by reissuing any of the run or single-step commands. 


[_] Up to 200 breakpoints can be set. 


a 


ba 


Setting a Software Breakpoint 


There are several ways to set a software breakpoint: 


1) Point to the line of assembly language code or C code where you'd like to 
set a breakpoint. 


2) Click the left button. 


Repeating this action clears the breakpoint. 


1) Make the FILE or DISASSEMBLY window the active window. 


2) Use the arrow keys to move the cursor to the line of code where you'd like 
to set a breakpoint. 


3) Press the key. 


Repeating this action clears the breakpoint. 


If you know the address where you’d like to set a software breakpoint, you can 
use the BA (breakpoint add) command. This command is useful because it 
doesn’t require you to search through code to find the desired line. The syntax 
for the BA command is: 


ba address 


This command sets a breakpoint at address. This parameter can be an abso- 
lute address, any C expression, the name of a C function, or the name of an 
assembly language label. You cannot set multiple breakpoints at the same 
statement. 


Using Software Breakpoints 9-3 


Clearing a Software Breakpoint 


9.2 Clearing a Software Breakpoint 


| 
ig?) 
el 
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br 


bd 


There are several ways to clear a software breakpoint. If you clear a breakpoint 
from an assembly language statement, the breakpointis also cleared from any 
associated C statement; if you clear a breakpoint from a C statement, the 
breakpoint is also cleared from the associated statement in the disassembly. 


1) Point to a breakpointed assembly language or C statement. 


2) Click the left button. 


1) Use the arrow keys or the DASM command to move the cursor to a break- 
pointed assembly language or C statement. 


2) Press the key. 


If you want to clear all the software breakpoints that are set, use the BR (break- 
point reset) command.This command is useful because it doesn’t require you 
to search through code to find the desired line. The syntax for the BR command 
is: 


br 


If you’dlike to clear one specific software breakpoint and you know the address 
of this breakpoint, you can use the BD (breakpoint delete) command. The syn- 
tax for the BD command is: 


bd address 


This command clears the breakpoint at address. This parameter can be an 
absolute address, any C expression, the name of a C function, or the name 
of an assembly language label. If no breakpoint is set at address, the debugger 
ignores the command. 
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9.3 Finding the Software Breakpoints That Are Set 


Sometimes you may need to know where software breakpoints are set. For 
example, the BD command's address parameter must correspond to the ad- 
dress of a breakpoint that is set. The BL (breakpoint list) command provides 
an easy way to get a complete listing of all the software breakpoints that are 
currently set in your program. The syntax for this command is: 


bl 


The BL command displays a table of software breakpoints in the COMMAND 
window display area. BL lists all the software breakpoints that are set, in the 
order in which you set them. Here’s an example of this type of list: 


Address Symbolic Information 
004d in main, at line 60, "c:\c5xhll\sample.c” 
0051 


The address is the memory address of the breakpoint. The symbolic informa- 
tion identifies the function, line number, and filename of the breakpointed C 
statement: 


[_] If the breakpoint was set in assembly language code, you'll see only an 
address unless the statement defines a symbol. 


[_] If the breakpoint was set in C code, you'll see the address together with 
symbolic information. 
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Customizing the Debugger Display 


The debugger display is completely configurable; you can create the interface 
that is best suited for your use. Besides being able to size and position indi- 
vidual windows, you can change the appearance of many of the display 
features, such as window borders, how the current statement is highlighted, 
etc. In addition, if you’re using a color display, you can change the colors of any 
area on the screen. Once you've customized the display to your liking, you can 
save the custom configuration for use in future debugging sessions. 


Topic Page 
10.1 Changing the Colors of the Debugger Display 10-2 
Area names: common display areas 10-3 

Area names: window borders 10-4 

Area names: COMMAND window 10-4 

Area names: DISASSEMBLY and FILE windows 10-5 

Area names: data-display windows 10-6 

Area names: menu bar and pulldown menus 10-7 

10.2 Changing the Border Styles of the Windows 10-8 
10.3 Saving and Using Custom Displays 10-9 
Changing the default display for monochrome monitors 10-9 
Saving a custom display 10-9 
Loading a custom display 10-10 
Invoking the debugger with a custom display 10-11 
Returning to the default display 10-11 

10.4 Changing the Prompt 10-12 
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10.1 Changing the Colors of the Debugger Display 


You can use the debugger with a color or a monochrome display; the com- 
mands described in this section are most useful if you have a color display. If 
you are using a monochrome display, these commands change the shades on 
your display. For example, if you are using a black-and-white display, these 
commands change the shades of gray that are used. 


color You canuse the COLOR or SCOLOR command to change the colors of areas 
> scolor 


in the debugger display. The format for these commands is: 


color area name, attribute; |, attributes [, attribute [, attributeg] | ] 
scolor area name, attribute; [, attributes [, attribute3 [, attribute] ] | 


These commands are similar. However, SCOLOR updates the screen imme- 
diately, and COLOR doesn’t update the screen (the new colors/attributes take 
effect as soon as the debugger executes another command that updates the 
screen). Typically, you might use the COLOR command several times, 
followed by an SCOLOR command to put all of the changes into effect at once. 


The area name parameter identifies the areas of the display that are affected. 
The attributes identify how the areas are affected. Table 10—1 lists the valid 
values for the attribute parameters. 


Table 10—1.Colors and Other Aitributes for the COLOR and SCOLOR Commands 


(a) Colors 
black blue green cyan 
red magenta yellow white 


(b) Other attributes 
bright blink 
The first two attribute parameters usually specify the foreground and 


background colors for the area. If you do not supply a background color, the 
debugger uses black as the background. 


Table 10-2 lists valid values for the area name parameters. This is a long list; 
the subsections following the table further identify these areas. 
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Table 10-2.Summary of Area Names for the COLOR and SCOLOR Commands 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


Note: Listing order is left to right, top to bottom. 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify either parameter. If you supply ambiguous 
attribute names, the debugger interprets the names in this order: black, blue, 
bright, blink. If you supply ambiguous area names, the debugger interprets 
them in the order that they’re listed in Table 10—2 (left to right, top to bottom). 


The remainder of this section identifies these areas. 


Area names: common display areas 


rd 
background 
qv 
Es 
r di 
blanks Sd 
PU 1 
Pc 00fc TOS o04£ ARO O9f7 
AR1 O09fb AR2 09fa AR3 fifo 
AR4 £080 ARS 09c6 AR6 Sfrases ee 
AR7 SBEEL sto 2e00 stl 4dfc 
Area identification Parameter name 
Screen background (behind all windows) background 
Window background (inside windows) blanks 
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Area names: window borders 


: j WATCH { TT : 
an inactive Me Serre aN win_border 
window | 
2: X+xX 4 Vv 
3 PC 0x0064 
/_———— win_resize 
rt ‘CO! 
eerie TMS320C5x Debugger i - 
Copyright (c) 1990, 1992 oes win_hiborder 
TMS320C5x Revision 1 ( 
Loading sample.out 
Done 
>>> 
Area identification Parameter name 
Window border for any window that isn’t active win_border 
The reversed “L” in the lower right corner of a resizable win_resize 
window 
Window border of the active window win_hiborder 


Area names: COMMAND window 


COMMAND 


cmd_echo pope 


file sample.c 


wa eee 


etree 


>>> go main | 


cmd_prompt cmd_input cmd_cursor 
Area identification Parameter name 
Echoed commands in display area cmd_echo 
Errors shown in display area error_msg 
Command-line prompt cmd_prompt 
Text that you enter on the command line cmd_input 
Command-line cursor cmd_cursor 
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Area names: DISASSEMBLY and FILE windows 


@ asm_cdata > 
,— DISASSEMBLY- 1 
0040 8aa0 fn: POPD *+ ——+— file _pc 
0041 80a0 SAR ARO, *+ | 7 
2 8180 SAR AR1, * 
asm_clabel 0043 b004 LAR ARO, #4 v 
asm_label——77™44 _00ea LAR ARO, a file_brk 
asm_data 
file_text 
file_line-———_____[- FE: tl.c 
00053 extern Cali, 
00054 extern meminit (): 
00055 main () file_pc_brk 
00056 { 
file_eof [teof | 
Area identification Parameter name 
Object code in DISASSEMBLY window that is associated asm_cdata 
with current C statement 
Object code in DISASSEMBLY window asm_data 
Addresses in DISASSEMBLY window asm_label 
Addresses in DISASSEMBLY window that are associated asm_clabel 
with current C statement 
Line numbers in FILE window file_line 
End-of-file marker in FILE window file_eof 
Text in FILE or DISASSEMBLY window file_text 
Breakpointed text in FILE or DISASSEMBLY window file_brk 
Current PC in FILE or DISASSEMBLY window file_pc 
Breakpoint at current PC in FILE or DISASSEMBLY file_pc_brk 
window 
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Area names: data-display windows 


field_label field_text 


field_hilite 
MEMORY A 
0090 0007 0007 000A 0007 3£fff ££00 


0007 0007 0000 3£££ 0000 0000 0002 
000e 0002 3£f£f£ O9f5 O9f5 affl ffff 
0015 OScGMestit stil ody) OSLO mmoLte 
001c 3fff 3fff $ff77 3fff 0000 0000 
0023 0900_ Shea ff£f£f 0000 0000 § 6ffff 


field_edit field_error 


Area identification Parameter name 


Label of a window field (includes register names in CPU field_label 
window, addresses in MEMORY window, index numbers 

and labels in WATCH window, member names in DISP 

window) 


Text of a window field (includes data values for all data- field_text 
display windows) and of most command output messages 
in command window 


Text of a highlighted field field_hilite 


Text of a field that has an error (Such as an invalid field_error 
memory location) 


Text of a field being edited (includes data values for all field_edit 
data-display windows) 
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Area names: menu bar and pulldown menus 


( menu_bar 

> 

Res ad Break Memory Color Mode 

r mentu_hilite 
menu_hicmd a 
menu cmd menu_enitry 

e menu_border J 
Area identification Parameter name 
Top line of display screen; background to main menu menu_bar 
choices 
Border of any pulldown menu menu_border 
Text of a menu entry menu_entry 
Invocation key for a menu or menu entry menu_cmd 
Text for current (selected) menu entry menu_hilite 
Invocation key for current (selected) menu entry menu_hicmd 
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10.2 Changing the Border Styles of the Windows 


10-8 


In addition to changing the colors of areas in the display, the debugger allows 
you to modify the border styles of the windows. 


border Use the BORDER command to change window border styles. The format for 


this command is: 
border [active window style] [,| inactive window style] [, resize style] | 


This command can change the border styles of the active window, the inactive 
windows, and any window that is being resized. The debugger supports nine 
border styles. Each parameter for the BORDER command must be one of the 
numbers that identifies these styles: 


Index Style 

Double-lined box 

Single-lined box 

Solid 1/2-tone top, double-lined sides and bottom 
Solid 1/4-tone top, double-lined sides and bottom 
Solid box, thin border 

Solid box, heavy sides, thin top and bottom 

Solid box, heavy borders 

Solid 1/2-tone box 

Solid 1/4-tone box 


ON Oa KrF WwW PS + CO 


Here are some examples of the BORDER command. Note that you can skip 
parameters, if desired. 


border 6,7,8 Change style of active, inactive, and resize windows 
border 1,,2 Change style of active and resize windows 
border ,3 Change style of inactive window 


You can execute the BORDER command as the Border selection on the Color 
pulldown menu. The debugger displays a dialog box so that you can enter the 
parameter values; in the dialog box, active window style is called foreground, 
and inactive window style is called background. 


Saving and Using Custom Displays 


10.3 Saving and Using Custom Displays 


The debugger allows you to save and use as many custom configurations as 
you like. 


When you invoke the debugger, it looks for a screen configuration file called 
init.clr. The screen configuration file defines how various areas of the display 
will appear. If the debugger doesn’t find this file, it uses the default screen con- 
figuration. Initially, init.clr defines screen configurations that exactly match the 
default configuration. 


The debugger supports two commands for saving and restoring custom 
screen configurations into files. The filenames that you use for restoring 
configurations must correspond to the filenames that you used for saving con- 
figurations. Note that these are binary files, not text files, so you can’t edit the 
files with a text editor. 


Changing the default display for monochrome monitors 


The default display is most useful with color monitors. The debugger highlights 
changed values, messages, and other information with color; this may not be 
particularly helpful if you are using a monochrome monitor. 


The debugger package includes another screen configuration file named 
mono.clr, which defines a screen configuration that can be used with 
monochrome monitors. The best way to use this configuration is to rename the 
file: 


1) Rename the original init.clr file—you might want to call it color.clr. 


2) Next, rename the mono.clr file. Call it init.clr. Now, whenever you invoke 
the debugger, it will automatically come up with a customized screen 
configuration for monochrome monitors. 


If you aren’t happy with the way that this file defines the screen configuration, 
you can customize it. 


Saving a custom display 


ssave Once you've customized the debugger display to your liking, you can use the 


SSAVE command to save the current screen configuration to a file. The format 
for this command is: 


ssave [filename] 
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This saves the screen resolution, border styles, colors, window positions, win- 
dow sizes, and (on PCs) video mode (EGA, VGA, etc.) for all debugging 
modes. 


The filename parameter names the new screen configuration file. You can 
include path information (including relative pathnames); if you don’t specify 
path information, the debugger places the file in the current directory. If you 
don’t supply a filename, the debugger saves the current configuration into a 
file named init.clr. 


Note that you can execute this command as the Save selection on the Color 
pulldown menu. 


Loading a custom display 
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sconfig Youcan use the SCONFIG command to restore the display to a particular con- 


figuration. The format for this command is: 
sconfig [filename] 


This restores the screen resolution, colors, window positions, window sizes, 
border styles, and (on PCs) video mode (EGA, CGA, MDA, etc.) saved in file- 
name. Screen resolution and video mode are restored either by changing the 
mode (on video cards with switchable modes) or by resizing the debugger 
screen (on other hosts). 


If you don’t supply a filename, the debugger looks for init.clr. The debugger 
searches for the file in the current directory and then in directories named with 
the D_DIR environment variable. 


Note that you can execute this command as the Load selection on the Color 
pulldown menu. 


a 


Note: 


The file created by the SSAVE command in this version of the debugger 
saves positional, screen size, and video mode information that was not 
saved by SSAVE in previous versions of the debugger. The format of this new 
information is not compatible with the old format. If you attempt to load an 
earlier version's SCONFIG file, the debugger will issue an error message 
and stop the load. 
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Invoking the debugger with a custom display 


If you set up the screen in a way that you like and always want to invoke the 
debugger with this screen configuration, you have two choices for 
accomplishing this: 


[_| Save the configuration in init.clr. 


[_.] Add a line to the batch file that the debugger executes at invocation time 
(init.cmd). This line should use the SCONFIG command to load the cus- 
tom configuration. 


Returning to the default display 


If you saved a custom configuration into init.clr but don’t want the debugger to 
come up in that configuration, rename the file or delete it. If you are in the 
debugger, have changed the configuration, and would like to revert to the de- 
fault, just execute the SCONFIG command without a filename. 
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Changing the Prompt 


10.4 Changing the Prompt 


prompt The debugger enables you to change the command-line prompt by using the 
s PROMPT command. The format of this command is: 
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prompt new prompt 


The new prompt can be any string of characters, excluding semicolons and 
commas. If you type a semicolon or a comma, it terminates the prompt string. 


Note that the SSAVE command doesn’t save the command-line prompt as part 
of a custom configuration. The SCONFIG command doesn’t change the 
command-line prompt. If you change the prompt, it stays changed until you 
change it again, even if you use SCONFIG to load a different screen configura- 
tion. 


If you always want to use a different prompt, you can add a PROMPT state- 
ment to the init.cmd batch file that the debugger executes at invocation time. 


You can also execute this command as the Prompt selection on the Color 
pulldown menu. 
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Note: 


Whenever you select a default group of processors, the group name be- 
comes the command-line prompt for the PDM. You cannot use the PROMPT 
command to change the PDM’s command-line prompt. To change the PDM 
prompt, use the SET command (see page 2-19). 
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Using the Analysis Interface 


The ’C5x on-chip analysis module allows the emulator to monitor hardware 
functions. The debugger provides you with easy-to-use windows, dialog 
boxes, and analysis commands that let you count occurrences of certain hard- 
ware functions or set hardware breakpoints on these occurrences. 


The debugger accesses the on-chip analysis module through a special set of 
pseudoregisters. The dialog boxes described in this chapter provide a trans- 
parent means of loading these registers. You will, in most cases, access the 
analysis features, unlike many of the other debugger features, through dialog 
boxes rather than through commands. If the dialog boxes do not meet your 
needs, you can use the special set of aliased commands that deal directly with 
the analysis pseudoregisters. These commands are described in Appendix A. 
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11.1. Introducing the Analysis Interface 11-2 
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11.6 Viewing the Analysis Data 11-14 
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Introducing the Analysis Interface 


11.1 Introducing the Analysis Interface 


The ’C5x analysis interface provides a detailed look into events occurring in 
hardware, thereby expanding your debugging capabilities beyond software 
breakpoints. The analysis interface examines ’C5x bus cycle information in 
real time and reacts to this information through actions such as hardware 
breakpoints and event counting. 


The analysis interface allows you to: 


(_] Count events. The analysis interface can count nine types of events. You 
have the option of either counting the number of times a defined event oc- 
curred during execution of your program or stopping after a certain num- 
ber of events are detected. 


The analysis module has an internal counterthat can count bus events as 
well as detect other internal events. Events that can be counted include: 


@ Data accesses i Interrupts or traps taken 

Mi Program accesses @ Returns from interrupts, traps, or calls 
@ CPU clock cycles i Instruction fetches 

@ Calls taken @ Branches taken 


@ Pipeline clocks 


You can count only one event at a time. 


(_} Set hardware breakpoints. You can also set up the analysis interface to 
halt the processor during execution of your program. The events that 
cause the processor to stop are called break events. A break event can 
define a variety of conditions, including: 


@ Data accesses @ Interrupts or traps taken 

i Discontinuity @ Returns from interrupts, traps, or calls 
Mi Program accesses Hi Pipeline clock 

@ Calls taken @ Branches taken 


@ Event counter passing zero 
i Low levels on EMUO/1 pins (EMUO and EMU1) 


Hardware break events allow you to set breakpoints in ROM, as well as set 
separate breakpoints on program and data accesses. This enables you to 
break on events that you cannot break on by using software breakpoints 
alone. In addition, any of the debugger’s basic features available with soft- 
ware breakpoints can also be used with hardware breakpoints. As a result, 
you can take advantage of all the step and run commands. 


Introducing the Analysis Interface 


(_} Set up EMU0/1 pins. In a system of multiple ’C5x processors connected 
by EMUO/1 (emulation event) pins, you can set up the EMU0/1 pins to 
create global breakpoints. Whenever one processor in your system reach- 
es a breakpoint (software or hardware), a// processors in the system can 
be halted. 


You can also set up the EMU0/1 pins to take advantage of the emulator’s 
external counter. The external counter keeps track of the internal counter; 
each time the internal counter passes zero, a signal is sent through the 
EMU0/1 pins, incrementing the external counter. 


(_} View the PC discontinuity stack. Discontinuity occurs when the ad- 
dresses fetched by the debugger become nonsequential as a result of 
loading the PC (through branches, calls, return instructions, for example) 
with new values. 


You can view these values through the PC discontinuity stack and easily 
track the progress of your program to see exactly how the debugger 
reached its current state. 
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An Overview of the Analysis Process 


11.2 An Overview of the Analysis Process 


Completing an analysis session consists of four simple steps: 


Enable the analysis interface. See Enabling the Analysis Inter- 


face, page 11-5. 
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Identify the events you'd like to See Defining the Conditions for 
track. Analysis, page 11-6. 


Run your program. See Running Your Program, 
page 11-13. 


View the analysis data. See Viewing the Analysis Data, 
page 11-14. 


Enabling the Analysis Interface 


11.3 Enabling the Analysis Interface 


To begin tracking hardware events, you must explicitly enable the interface by 
selecting Enable on the Analysis menu. When you select enable, the next time 
you open the menu, Enable is replaced by Disable. 


Figure 11-1. Enabling/Disabling the Analysis Interface 


— 
Analysis Toggles Analysis 
oC 


Selecting Disable turns the interface off; however, all events you previously en- 
abled remain unchanged. By default, when the debugger comes up, the analy- 
sis interface is disabled. 


During a single debugging session, you may want to change the parameters 
of the analysis module several times. For example, you may want to define 
new parameters such as data bus accesses, tracking CPU clock cycles, etc. 
To do this, you must open the individual dialog boxes, deselect any previous 
events, and select the new events you want to track. 
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Note: 


You have to enable the analysis interface only once during a debugging ses- 
sion. It is not necessary to enable the analysis interface each time you run 


your program. 
| ee | 
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11.4 Defining Conditions for Analysis 


Counting events 


The analysis module detects hardware events and monitors the internal sig- 
nals of the processor. The interface to the analysis module allows you to define 
parameters that count events or halt the processor. 


First, however, you must define the conditions the analysis interface must 
meet to track a particular event. To do this, select the events you want to track 
by enabling the appropriate conditions in the Analysis Count Events, Analysis 
Break Events, or Emulator Pins dialog boxes found on the Analysis menu. 


You can count two basic types of events: 


__] Simple events 
[.] Bus address accesses 


Figure 11-2 shows the Analysis Count Events dialog box and the types of 
events that you can select. 


Figure 11-2. Two Basic Types of Events Can Be Counted 


Bus address 
accesses 


Analysis Count Events 


( )Program bus ( )Call taken (*) Instruction fetch 


)Data bus (\)Branch taken (_)Pipeline clock 


( \Interrupt/trap taken )CPU clock 


( )WReturn taken 


Program bus: (*) Access 


Address (1) ( ) Fetch 
( )Read 


( )Write 


Data Bus: (*) Access 


Address (6) ( )Read 


( )Write 


Internal Counter 


<< OK >> < Cancel > 


Simple events 


Event counting is mutually exclusive; therefore, you can count only one event 
at a time. To show an enabled event in the Analysis Count Events dialog box, 
the debugger displays an asterisk inside the parentheses preceding your 
selection. In this example, the debugger counts the number of instructions 
fetched. (Refer to Section 5.3 on page 5-11 for more information about select- 
ing events in dialog boxes.) 


Enabled event 


Count 100 
branches 


Enable event counter to 
halt the processor when 
the counter passes zero 


Defining Conditions for Analysis 


You can use event counting in one of two ways; you can either stop after a cer- 
tain number of events are detected, or you can count the number of times a 
defined event occurs. To count the number of times an event occurred, simply 
enable the event in the Analysis Count Events dialog box as shown in 
Figure 11-2. 


The analysis module has an internal counter that can count bus events as well 
as detect other internal events. This counter keeps track of how many times 
an event occurs. Therefore, in order to stop after a certain number of events 
are detected, you must: 


[__] Specify the event you want to count, 
[_] Enable the internal counter (Break < 0), and 
[| Load the counter with the number of events you want to count. 


The internal counter decrements each time the specified event is detected. 


For example, you may wantto follow the progress of the branches taken during 
execution of your program, but you may want the processor to stop after 100 
branches have occurred. In this case, the counter is responsible for keeping 
track of the branches taken and signaling the processor to stop after the 100th 
branch event occurs. When the internal counter passes zero, the debugger will 
halt the processor. 


Figure 11-3. Enabling the Event Counter 


Analysis Count Events 


( )Program bus ( )Call taken ( ) Instruction fetch 


( )Data bus (*) Branch taken ( )Pipeline clock 


(_)Interrupt/trap taken ( \iGPUNelock 
( )Return taken 
Program bus: 


Address (1) 


( )Access 
[0x2080 ( }Fetch 
(*) Read 


(2) 
(3) 
(4) 
( )Write (5) 
Data Bus: 

Address (6) 


(*) Access 
( )Read 
( )Write 


(7) 
(8) 
(9) 


[0x0800 


Internal Counter (lees X] Break < 0 


<< OK >> < Cancel > 


To watch the progress of the event counter, open the Analysis window by se- 
lecting View on the Analysis menu. For more information concerning the Anal- 
ysis window, see Section 11.6 on page 11-14. 
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Defining Conditions for Analysis 


Halting the processor 


You can set a hardware breakpoint on three basic types of events: 


[_.} Event counter passing zero 
__] Simple events 
[.] Bus address accesses 


Figure 11-4 shows the Analysis Break Events dialog box and the different 
types of break events that you can select. 


Figure 11-4. Three Basic Types of Break Events 


Bus address 
accesses 


‘Analysis Break Events 


[X]Program bus [X]Call taken [X]Pipeline clock 
]Data bus [X]Branch taken [X]EMUO driven low 
[ ]Discontinuity [}J ]Interrupt/trap taken [ ]EMU1 driven low 


]Return taken [,]Event Counter < 0 


Program bus: (*)Access (2) 
Address (1) (3) 
(4) 
(5) 


Data Bus: 

Address (6) q (7) 
(8) 
(9) 


Simple events Event counter 


These are events that cause the processor to halt when a specified event is 
detected: 


[_] Event counter < 0 [_] Interrupts or traps taken 

[_] Calls taken [_] Returns from interrupts, traps, or calls 
[_] Branches taken [_] Discontinuity 

[_] Instruction fetches [_] Low levels on EMU0/1 pins 

[_] Pipeline clocks 


Enabling events in the Analysis Break Events dialog box is like turning a switch 
on and off. When an event is enabled, the debugger displays an X next to the 
event. You can enable as many events as you want. 


In Figure 11—4, the debugger halts the processor whenever it detects the oc- 
currence of a call taken, branch taken, instruction fetch, the EMUO pin driven 
low, or a program or data bus access. 


Defining Conditions for Analysis 


Setting up the event comparators 


The analysis module has separate event comparators for the program and 
data buses. You can set up the analysis interface either to count the number 
of accesses to a certain bus address or to halt the processor on accesses to 
a specified address. 


The program and data bus fields in the Analysis Break Events dialog box are 
identical to the program and data bus fields found in the Analysis Count Events 
dialog box. (Notice that the event comparators shown in Figure 11-2, 
Figure 11-3, and Figure 11-4 all have the same values.) As a result, changing 
the values in these fields in either dialog box affects bothof these dialog boxes. 


The program bus supports noninstruction read and write accesses and 
instruction fetches. If you enable the Access qualifier, noninstruction reads 
and writes are detected. If you enable the Fetch qualifier, only program fetches 
are detected. 


Similarly, if you were to load the data address field with 0x0800 and select Ac- 
cess in the Analysis Break Events dialog box, the processor would halt every 
time a read or write occurs on the data bus at address 0x0800: 


Analysis Break Events 


Data Bus: 
Address (6) 


Break when a read or write 
occurs at address 0x0800 
on the data bus 


Look for reads 
or writes 


Enabling one of these comparators in the Analysis Count Events dialog box 
allows you to count the number of accesses that are detected or to stop after 
a certain number of accesses have occurred. 
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Defining Conditions for Analysis 


In Figure 11-5, several events, including the data bus, are enabled in the Anal- 
ysis Break Events dialog box; however, data and program bus accesses need 
further qualification: 


[.} Address qualification 
[_] Access qualification 


For example, Read and My_Symbol! selected for the data bus in Figure 11-5 
represent access and address qualifiers, respectively. They further define the 
conditions necessary to halt the emulator. 


Figure 11-5. Enabling Break Events 
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Address 
qualifier 


‘Analysis Break Events 


[X]Program bus [X]Call taken [X]Pipeline clock 
[X]Data bus [X]Branch taken [ ]EMUO driven low 
[ ]Discontinuity [X]Interrupt/trap taken [X]EMU1 driven low 


[ ]Return taken [ ]Event Counter < 0 


Program bus: ( )Access (2) 
Address (L ( )Fetch (3) 
)Read (4) 

( )Write (5) 


( )Access (7) 
Address (6) (*) Read (8) 


( )Write (9) 


<< OK >> < Cancel > 


Access 
qualifier 


Address qualification allows you to enter an address expression (a specific ad- 
dress, symbol, or function name). Access qualification allows you to track 
reads, writes, both reads and writes (accesses), or program fetches to asingle 
address. In Figure 11-5, the debugger halts the processor any time a read 
from the address at My_Symbol occurs. 


Defining Conditions for Analysis 


Setting up the EMU0/1 pins 
The analysis interface allows you to access and set up the EMU0/1 (emulation 
event) pins on your processor to: 


[_.} Use the emulator’s external counter, or 
[__] Set global breakpoints. 


Selecting EMU0/1 from the Analysis menu opens the Emulator Pins dialog box 
shown in Figure 11-6. 


Figure 11-6. The Emulator Pins Dialog Box 


Emulator Pins 


[ ]EMUO trigger out 
[ ]EMU1 trigger out 


[ ]External Clock 


<<OK>> <Cancel> 


The emulator’s external counter keeps track of the internal counter. The inter- 
nal counter is a 16-bit, count-down counter that can keep track of a maximum 
of 65,536 events. The external counter, however, is a 32-bit, incremental 
counter. Each time the internal counter passes zero, a signal sent through the 
EMU0/1 pins increments the external counter. To use the emulator’s external 
counter, simply enable the external clock parameter in the Emulator Pins dia- 
log box. (Refer to Section 5.3, page 5-11, for more information on enabling pa- 
rameters in a dialog box.) 


When you enable the external clock, the EMU0/1 pins are set up as 
totem-pole outputs; otherwise, the EMUO/1 pins are set up as 
open-collector outputs. You can set up only one ’C5x device in the 
system to use the external counter. In doing so, no other device in 
the system can have EMU0/1 pins set up to trigger out. 


The EMU1 pin provides a ripple-carry output signal from the 
internal counter that increments the emulator counter. The ’C5x 
EMUO pin is set up to send a signal to the debugger when a 
hardware or software breakpoint occurs. Other devices in the 
system can still be programmed to detect low levels on the EMUO 
pin to provide you with global breakpoint capabilities. 
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Defining Conditions for Analysis 


Notes: 


(_} Enabling the external clock disables all options concerning the internal 
clock in the Analysis Break Events and Analysis Count Events dialog 
boxes. 


[_] Enabling the external clock in the Emulator Pins dialog box has the fol- 
lowing restrictions: 


M Youcan enable only one external clock when you have multiple pro- 
cessors in a system (that are connected by their EMU0/1 pins). 


@ No other external devices can actively drive the EMU0/1 pins. 


By default, the EMU0/1 pins are set up as input signals; however, you can set 
them up as output signals or trigger out whenever the processor is halted by 
a software or hardware breakpoint. This is extremely useful when you have 
multiple C5x processors in a system connected by their EMUO/1 pins. 


Selecting EMU0/1 does not, however, automatically halt all processors in the 
system. To do so, you must enable the EMU0/1 driven low condition in the 
Analysis Break Events dialog box. For example, if you have a system consist- 
ing of two processors connected by their EMUO pins, and you want to halt both 
processors when this pin is driven low, you would enable the EMU0 trigger out 
parameter. Then you must enable the parameter EMUO driven /owin the Anal- 
ysis Break Events dialog box. See Figure 11-7. 


Figure 11-7. Setting Up Global Breakpoints on a System of Two ’C5x Processors 
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Emulator Pins 


Processor 1 


and [X]EMUO trigger out 
Processor 2 [ ]EMU1 trigger out 
[ ]External Clock 


<<OK>> <Cancel> 


Analysis Break Events 
Processor 1 7 


and [ ]Program bus [ ]Call taken [ ]Pipeline clock 
Processor 2 [ ]Data bus [ ]Branch taken [X]EMUO driven low 
[ ]Discontinuity [ ]Interrupt/trap taken { ]EMU1 driven low 
[ ]Return taken [ ]Event Counter < 0 


Setting up each processor in this way creates a global breakpoint so that any 
processor that reaches a breakpoint halts all the other processors in the sys- 
tem. 


Running Your Program 


11.5 Running Your Program 


Once you have defined your parameters, the analysis interface can begin col- 
lecting data as soon as you run your program. It will stop collecting data when 
the defined conditions are met. The analysis interface monitors the progress 
of the defined events while your program is running. The basic syntax for the 
RUN command is: 


run [expression] 


You can use any of the debugger run commands (STEP, CSTEP, NEXT, etc.) 
described in Chapter 7 except the RUNF (run free) command. 


The analysis interface provides capabilities in addition to those provided by the 
RUNB command. You may notice that with the RUNB command you can count 
the number of CPU clock cycles only during the execution of a specific section 
of code. However, the analysis interface not only allows you to count CPU 
clock cycles, it also allows you to count other events. 


cc cca | 
Note: 


The conditions for the analysis session must be defined before your analysis 
session begins; you cannot change conditions during execution of your pro- 


gram. 
|) 
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11.6 Viewing the Analysis Data 


You can monitor the status of the analysis interface by selecting View on the 
Analysis menu. This window displays an ongoing progress report of the analy- 
sis module’s activity. Through this window, you can monitor the status of the 
break events, the value of both the internal and external event counters, and 
the values of the PC discontinuity stack. An example of the Analysis window 
is shown below. 


Figure 11-8. Analysis Interface View Window, Displaying an Ongoing Status Report 


Status field 
Prog,Call 
F ie 20A6 linenumber : function name 
oe 2083 linenumber : function name 


ZO) linenumber : function Kame 
4095 


Code 


Change of the 


Internal counter internal counter 


Interpreting the status field 


The STAT field displays a list of the events that caused the processor to halt. 
If the analysis interface itself did not halt the processor, but something else 
(such as a software breakpoint) did, then the status line will display: “No event 
detected”. 


Multiple events can cause the processor to halt at the same time; these events 
are reflected in the STAT field of the Analysis window. 


Interpreting the discontinuity stack 
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The PC discontinuity stack allows you to see how the program reached its cur- 
rent position. The Analysis window displays both the PC discontinuity stack 
values and the corresponding C code. A program discontinuity occurs when 
the program addresses fetched by the debugger become nonsequential as a 
result of an action such as a branch or interrupt. 


The Analysis window has three fields that represent the PC discontinuity stack: 


Analysis Field Description 
PTO displays the address of the current code segment 
PT1 displays the address of the previous code segment 


PT2 displays the address of the oldest code segment 


Viewing the Analysis Data 


For example, suppose you set a software breakpoint at address 0x20A8 and 
the processor stopped on it. 


Example 11-1. Sample Code and PC Discontinuity Values 


(a) Sample code 


Address Code Comment 
2071 B call.EPIO_2,* 

2073 call.L10: MAR *, AR2 PT2 address 
207E LACC *, ARL 

207F SACL a+ 

2080 CALL xcall,* 

2082 MAR = 

2083 B call.L8 PT1 address 
20A4 PSHD Z* 

20A5 RET 

20A6 xcall: POPD *+ PTO address 
20A7 SAR ARO, *+ 

20A8 > SAR ARI, * BP address 
BC 20A6 

TO 2083 

FR 2073 


(b) PC discontinuity stack 


Analysis 


PTO 20A6 no function 
PT1 2083 no function 
Pe 2073 no function 


If you look at the PC discontinuity stack shown in Example 11-1 (b), you see 
that your program reached this point through a branch from address 0x2071 
and a call from address 0x2080. The PT2 and PT1 trace addresses contain 
the last addresses fetched before the branch and call instructions were 
executed. The PTO trace address contains the destination of the call. 
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Viewing the Analysis Data 


The fields next to the PTO, PT1, and PT2 fields list the C code associated with 
these addresses. This includes the function name and the line number within 
the function that caused the discontinuity. If no corresponding C code exists, 
the debugger displays “no function”. Clicking on any field in the PC 
discontinuity stack will cause the FILE and DISASSEMBLY windows to open 
(in the assembly or mixed mode). The address for that field is displayed in the 
DISASSEMBLY window, while the associated C code is shown in the FILE 
window. This allows you to easily track the PC discontinuity values back to their 
original source. 


Interpreting the event counter 


11-16 


You can watch the progress of the event counters in the Analysis window. The 
CLK field displays the internal and external counter values with the appropriate 
prefix—l for internal, and X for external. The value shown next to the internal 
event counter represents the difference from the last counter value (delta). You 
can change the value of the internal counter by clicking on the appropriate field 
and entering a new value. 


| 


Note: 


When counting CPU clock cycles, the counter value reflects startup and la- 
tency cycles. 


| | 
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Profiling Code Execution 


The profiling environment is a special debugger environment that lets you 
collect execution statistics for your code. This environment is available on all 
debugger platforms except DOS. 


Note that the profiling environment is separate from the basic debugging envi- 
ronment; the only way to switch between the two environments is by exiting 
and then reinvoking the debugger. 
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An Overview of the Profiling Process 


12.1 An Overview of the Profiling Process 


Profiling consists of five simple steps: 


Enter the profiling environment. See Entering the Profiling Envi- 


ronment, page 12-3. 


Identify the areas of code where See Defining Areas for Profiling, 
you'd like to collect statistics. page 12-5. 


| 
[Sane] \Z 


Identify the profiling session See Defining a Stopping Point, 
stopping points. page 12-13. 
[Ste] \ 
Begin profiling. See Running a Profiling Ses- 
sion, page 12-15. 


View the profile data. See Viewing Profile Data, page 
12-17. 


Note: 


When you compile a program that will be profiled, you must use the —g and 
the —as options. The—g option includes symbolic debugging information; the 
—as option ensures that you will be able to include ranges as profile areas. 


| 


A profiling strategy 


The profiling environment provides a method for collecting execution statistics 
about specific areas in your code. This gives you immediate feedback on your 
application’s performance. Here’s a suggestion for a basic approach to opti- 
mizing the performance of your program. 


1) Mark all the functions in your program as profile areas. 
) Runa profiling session; find the busiest functions. 

3) Unmark all the functions. 
) 


Mark the individual lines in the busy functions and run another profiling 
session. 
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12.2 Entering the Profiling Environment 


The profiling environment is available on all debugger platforms except DOS. 
To enter the profiling environment, invoke the debugger with the —-profile op- 
tion. At the system command line, enter the appropriate command: 


emulator: 
simulator: 
EVM: 


emu5x -profile 
sim5x -profile 
evm5x -profile 


Entering the Profiling Environment 


Use any additional debugger options that you desire (—b, —p, etc.). 


Restrictions of the profiling environment 


Some restrictions apply to the profiling environment: 


L} 
L] 


You'll always be in mixed mode. 


COMMAND, DISASSEMBLY, FILE, and PROFILE are the only windows 
available; additional windows, such as the WATCH window, cannot be 


opened. 


Breakpoints cannot be set. (However, you can use a similar feature called 
stopping points when you mark sections of code for profiling.) 


The profiling environment supports only a subset of the debugger 
commands. Table 12-1 lists the debugger commands that can and can’t 


be used in the profiling environment. 


Table 12-1. Debugger Commands That Can/Can't Be Used in the Profiling Environment 


Can be used 


FUNC 
IF/ELSE/ENDIF 
LOAD 


LOOP/ENDLOOP 


MA 


SCONFIG 
SIZE 
SLOAD 
SYSTEM 
TAKE 
UNALIAS 
USE 
VERSION 
WIN 
ZOOM 


Can’t be used 


ADDR MIX 
ASM MS 

BA NEXT 
BD PATCH 
BL RETURN 
BORDER RUN 

BR RUNB 

Cc RUNF 
CALLS SCOLOR 
CNEXT SETF 
COLOR SOUND 
CSTEP SSAVE 
DISP STEP 
FILL WA 

GO WD 
HALT WHATIS 
MEM WR 


Be sure you don’t use any of the “can’t be used” commands in your initial- 


ization batch file. 
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Using pulldown menus in the profiling environment 
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The debugger displays a different menu bar in the profiling environment: 


“ 


Load mAp Mark Enable Disable Unmark View Stop-points Profile 


dj 


The Load menu corresponds to the Load menu in the basic debugger environ- 
ment. The mAp menu provides memory map commands available from the 
basic Memory menu. The other entries provide access to profiling commands 
and features. 


The profiling environment’s pulldown menus operate similarly to the basic 
debugger pulldown menus. However, several of the menus have additional 
submenus. A submenu is indicated by a > character following a menu item. For 
example, here’s one of the submenus for the Mark menu: 


Mark 


Asm level > Line areas > 
Range areas > Explicitly 
Function areas > Bi o Wo} eX het oYo} oe Moye] 


Chapter 13, Summary of Commands and Special Keys, shows which debug- 
ger commands are associated with the menu items in the basic debugger pull- 
down menus. Because the profiling environment supports over 100 profile- 
specific commands, it’s not practical to show the commands associated with 
the menu choices. Here’s a tip to help you with the profiling commands: the 
highlighted menu letters form the name of the corresponding debugger com- 
mand. For example, if you prefer the function-key approach to using menus, 
the highlighted letters in Mark— C level-Line areas—in one Function show 
that you could press @D @), ©), ©, ®. This also shows that the correspond- 
ing debugger command is MCLF. 


Defining Areas for Profiling 


12.3 Defining Areas for Profiling 


Marking an area 


Within the profiling environment, you can collect statistics on three types of 
areas: 


[_] Individual lines in C or disassembly 
[|_| Ranges in C or disassembly 
[| Functions in C only 


To identify any of these areas for profiling, mark the line, range, or function. You 
can disable areas so that they won’t affect the profile data, and you can re-en- 
able areas that have been disabled. You can also unmark areas that you are 
no longer interested in. 


The mouse is the simplest way to mark, disable, enable, and unmark tasks. 
The pulldown menus also support these tasks and more complex tasks. 


The following subsections explain how to mark, disable, re-enable, and 
unmark profile areas by using the mouse or the pulldown menus. The individu- 
al commands are summarized in Restrictions of the profiling environment on 
page 12-3. Restrictions on profiling areas are summarized on page 12-12. 


Marking an area qualifies it for profiling so that the debugger can collect timing 
statistics about the area. 


Remember, to display C code, use the FILE or FUNC command; to display dis- 
assembly, use the DASM command. 


Notes: 


[| Marking an area in C does not mark the associated code in disassem- 
bly. 


[_] Areas can be nested; for example, you can mark a line within a marked 
range. The debugger will report statistics for both the line and the func- 
tion. 


(_] Ranges cannot overlap, and they cannot span function boundaries. 
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S Marking a line. These instructions apply to both C and disassembly. 


a 1) Point to the line you want to mark. 


if 2) Click the left mouse button. 
The beginning of the line will be highlighted with a blinking >>. 


1 3) Click the left mouse button again. 
The beginning of the line will be highlighted with Le> (line enabled). 


Marking a range. These instructions apply to both C and disassembly. 
\ 1) Point to the first line of the range you want to mark. 


10 2) Click the left mouse button. 
The beginning of the line will be highlighted with a blinking >>. 


\ 3) Point to the last line of the range. 


I 4) Click the left mouse button again. 
The beginning of the line will be highlighted with Re> (range enabled), 
marking the beginning of the range. The last line will be highlighted with 
<<, marking the end of the range. 


Marking a function. These instructions apply to C only. 


By 1) Point to the statement that declares the function you want to mark. 


10 2) Click the left mouse button. 
The beginning of the line will be highlighted with Fe> (function enabled). 
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Table 12-2 lists the menu selections for marking areas. The highlighted areas 
show the keys that you can use if you prefer to use the function-key method 
of selecting menu choices. 


Table 12—2.Menu Selections for Marking Areas 


Disabling an area 


C only: Disassembly only: 

To mark this area Mark-—C level Mark—Asm level 
Lines Line areas —Line areas 
LJ By line numbert Explicitly Explicitly 
(} All lines in a function in one Function in one Function 
Ranges —Range areas —Range areas 
[J By line numberst Explicitly Explicitly 
Functions —Function areas 
(] By function name Explicitly . 

. . ; not applicable 
(] All functions in a module in one Module 
_] All functions everywhere Globally 


TC areas are identified by line number; disassembly areas are identified by address. 


Attimes, it is useful to identify areas that you don’t want to impact profile statis- 
tics. To do this, you should disable the appropriate area. Disabling effectively 
subtracts the timing information of the disabled area from all profile areas that 
include or call the disabled area. Areas must be marked before they can be 
disabled. 


For example, if you have marked a function that calls a standard C function 
such as malloc(), you may not want malloc() to affect the statistics for the call- 
ing function. You could mark the line that calls malloc(), and then disable the 
line. This way, the profile statistics for the function would not include the statis- 
tics for malloc(). 


TTT 
Note: 


If you disable an area after you've already collected statistics on it, that infor- 


mation will be lost. 
| | 
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The simplest way to disable an area is to use the mouse, as described below. 


S Disabling a line area: 


Ss 1) Point to the marked line. 
Il 2) Click the left mouse button once. 
The beginning of the line will be highlighted with Ld> (line disabled). 
Disabling a range area: 
1) Point to the marked line. 
Il 2) Click the left mouse button once. 


The beginning of the line will be highlighted with Rd> (range disabled). 


Disabling a function area: 


a 1) Point to the marked statement that declares the function. 


Il 2) Click the left mouse button once. 
The beginning of the line will be highlighted with Fd> (function disabled). 
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Table 12-—3.Menu Selections for Disabling Areas 


To disable this area 

Lines 

LJ By line numbert 

[] All lines in a function 

_] All lines in a module 

_] All lines everywhere 
Ranges 

LJ By line numberst 

[J All ranges in a function 
(] All ranges in a module 
(] All ranges everywhere 
Functions 

(] By function name 

[] All functions in a module 
_] All functions everywhere 
All areas 

(] All areas in a function 


(] All areas in a module 


_] All areas everywhere 


C only: 
Disable->C level 


—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Function areas 
Explicitly 
—in one Module 
Globally 
—All areas 
—in one Function 
—in one Module 


Globally 


Disassembly only: 
Disable-Asm level 


—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
—in one Function 
—in one Module 


—Globally 


not applicable 


~All areas 
sin one Function 
sin one Module 


Globally 


Defining Areas for Profiling 


Table 12-3 lists the menu selections for disabling areas. The highlighted areas 
show the keys that you can use if you prefer to use the function-key method 
of selecting menu choices. 


C and disassembly: 
Disable—Both levels 


—Line areas 
not applicable 
—in one Function 
—in one Module 
Globally 
—Range areas 
not applicable 
—in one Function 
—in one Module 
Globally 
—Function areas 
not applicable 
—in one Module 
Globally 
—All areas 
—in one Function 
—in one Module 


Globally 


t C areas are identified by line number; disassembly areas are identified by address. 
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Re-enabling a disabled area 


When an area has been disabled and you would like to profile it once again, 
you must enable the area. To use the mouse, just point to the line, the function, 
or the first line of a range, and click the left mouse button; the range will once 
again be highlighted in the same way as a marked area. 


Table 12-—4.Menu Selections for Enabling Areas 


To enable this area 

Lines 

LJ By line numbert 

(} All lines in a function 

(} All lines in a module 

_j All lines everywhere 
Ranges 

LJ By line numberst 

(] All ranges in a function 
(J All ranges in a module 
_] All ranges everywhere 
Functions 

(] By function name 

(] All functions in a module 
_] All functions everywhere 
All areas 

_] All areas in a function 


(} All areas ina module 


(] All areas everywhere 


t Careas are identified by line number; disassembly areas are identified by address. 
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C only: 
Enable-C level 


—Line areas 
Explicitly 
in one Function 
in one Module 
Globally 
—Range areas 
Explicitly 
—in one Function 
in one Module 
Globally 
—Function areas 
Explicitly 
in one Module 
Globally 
—All areas 
in one Function 
—in one Module 


Globally 


Disassembly only: 
Enable—Asm level 


—Line areas 
Explicitly 
in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
—in one Function 
in one Module 


Globally 


not applicable 


All areas 
sin one Function 
sin one Module 


Globally 


In addition to using the mouse, you can enable an area by using one of the 
commands listed in Table 12—4. However, the easiest way to enter these com- 
mands is by accessing them from the Enable menu. 


C and disassembly: 
Enable-Both levels 


—Line areas 
not applicable 
—in one Function 
—in one Module 
Globally 
—Range areas 
not applicable 
—in one Function 
in one Module 
Globally 
—Function areas 
not applicable 
in one Module 
Globally 
—All areas 
—in one Function 
—in one Module 


Globally 


Unmarking an area 


OK 


Ht 


OK 


Defining Areas for Profiling 


If you want to stop collecting information about a specific area, unmark it. You 
can use the mouse or key method. 


Unmarking a line area: 

1) Point to the marked line. 

2) Click the right mouse button once. 

The line will no longer be highlighted. 

Unmarking a range area: 

1) Point to the marked line. 

2) Click the right mouse button once. 

The line will no longer be highlighted. 

Unmarking a function area: 

1) Point to the marked statement that declares the function. 


2) Click the right mouse button once. 


The line will no longer be highlighted. 
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Table 12-5.Menu Selections for Unmarking Areas 


To unmark this area 

Lines 

Cy By line numbert 

(} All lines in a function 

(j All lines in a module 

_j All lines everywhere 
Ranges 

[J By line numberst 

(] All ranges in a function 
_] All ranges in a module 
_] All ranges everywhere 
Functions 

_] By function name 

(] All functions in a module 
_] All functions everywhere 
All areas 

(] All areas in a function 


(j All areas in a module 


(] All areas everywhere 


tT C areas are identified by line number; disassembly areas are identified by address. 


C only: 
Unmark->C level 


—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
in one Function 
in one Module 
Globally 
—Function areas 
Explicitly 
—in one Module 
Globally 
—All areas 
in one Function 
—in one Module 


Globally 


Restrictions on profiling areas 


Table 12—5 lists the selections on the Unmark menu. 


Disassembly only: 
Unmark—><Asm level 


—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
in one Function 
in one Module 


Globally 


not applicable 


~All areas 
sin one Function 
sin one Module 


Globally 


The following restrictions apply to profiling areas: 


LJ 
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C and disassembly: 
Unmark—>Both levels 


—Line areas 
not applicable 
—in one Function 
—in one Module 
Globally 
—Range areas 
not applicable 
in one Function 
in one Module 
Globally 
—Function areas 
not applicable 
—in one Module 
Globally 
—All areas 
in one Function 
—in one Module 


Globally 


There must be a minimum of three instructions between a delayed branch 
and the beginning of an area. 


An area cannot begin or end on the RPTS instruction or on the instruction 


to be repeated. 


An area cannot begin or end on the last instruction of a repeat block. 


Defining a Stopping Point 


12.4 Defining a Stopping Point 


a 


a 


Before you run aprofiling session, you mustidentify the point where the debug- 
ger should stop collecting statistics. By default, C programs contain an exitla- 
bel, and this is defined as the default stopping point when you load your pro- 
gram. (You can delete exit as a stopping point, if you wish.) If your program 
does not contain an exit label, or if you prefer to stop at a different point, you 
can define another stopping point. You can set multiple stopping points; the 
debugger will stop at the first one it finds. 


Each stopping point is highlighted in the FILE or DISASSEMBLY window with 
a * character at the beginning of the line. Even though no statistics can be 
gathered for areas following a stopping point, the areas will be listed in the 
PROFILE window. 


You can use the mouse or commands to add or delete a stopping point; you 
can also use commands to list or reset all the stopping points. 


_——————— “= “(0 0  — — e —  —_—<@ouoo8€8e— mn 
Note: 


You cannot seta stopping point on a statement that has already been defined 


as a part of a profile area. 
SS oe os v S 


To set a stopping point: 


1) Point to the statement that you want to add as a stopping point. 


2) Click the right mouse button. 


To remove a stopping point: 


1) Point to the statement marking the stopping point that you want to delete. 


2) Click the right mouse button. 


Profiling Code Execution 12-13 


Defining a Stopping Point 


The debugger supports several commands for adding, deleting, resetting, and 


listing stopping points (described below); all of these commands can also be 
entered from the Stop-points menu. 


sa To add a stopping point, use the SA (stop add) command. The syntax for this 
command is: 


sa address 


This adds address as a stopping point. The address parameter can be a label, 
a function name, or a memory address. 


sd To delete a stopping point, use the SD (stop delete) command. The syntax for 
this command is: 


sd address 


This deletes address as a stopping point. As for SA, the addresscan be a label, 
a function name, or a memory address. 


sr To delete all the stopping points at once, use the SR (stop reset) command. 
The syntax for this command is: 


sr 


This deletes all stopping points, including the default exit (if it exists). 


sl To see a list of all the stopping points that are currently set, use the SL (stop 
list) command. The syntax for this command is: 


sl 
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12.5 Running a Profiling Session 


pq 


Once you have defined profile areas and a stopping point, you can run a profil- 
ing session. You can run two types of profiling sessions: 


[__| A full profile collects a full set of statistics for the defined profile areas. 


_} A quick profile collects a subset of the available statistics (it doesn’t 
collect exclusive or exclusive max data, which are described in Section 
12.6). This reduces overhead because the debugger doesn’t have to track 
entering/exiting subroutines within an area. 


The debugger supports commands for running both types of sessions. In addi- 
tion, the debugger supports a command that helps you to resume a profiling 
session. All of these commands can also be entered from the Profile menu. 


To run a full profiling session, use the PF (profile full) command. The syntax 
for this command is: 


pf starting point|[, update rate] 


To run a quick profiling session, use the PQ (profile quick) command. The 
syntax for this command is: 


pq_ starting point [, update rate] 


The debugger will collect statistics on the defined areas between the starting 
point and the stopping point. The starting point parameter can be a label, a 
function name, or a memory address. There is no default starting point. 


The update rate is an optional parameter that determines how often the statis- 
tics listed in the PROFILE window will be updated. The update rate parameter 
can have one of these values: 


0 An update rate of 0 means that the statistics listed in the PROFILE 
window are not updated until the profiling session is halted. A 
“spinning wheel” character will be shown at the beginning of the 
PROFILE window label line to indicate that a profiling session is in 
progress. 0 is the default value. 


>1 If a number greater than or equal to 1 is supplied, the statistics in the 
PROFILE window are updated during the profiling session. If a value 
of 1 is supplied, the data will be updated as often as possible. When 
larger numbers are supplied, the data is updated less often. 


<0 If a negative number is supplied, the statistics listed in the PROFILE 
window are not updated until the profiling session is halted. The “spin- 
ning wheel” character is not displayed. 
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pr 


No matter which update rate you choose, you can force the PROFILE window 
to be updated during a profiling session by pointing to the window header and 
clicking a mouse button. 


After you enter a PF or PQ command, your program restarts and runs to the 
defined starting point. Profiling begins when the starting point is reached and 
continues until a stopping point is reached or until you halt the profiling session 
by pressing (ESC). 


Use the PR command to resume a profiling session that has halted. The syntax 
for this command is: 


pr [clear data [, update rate]] 


The optional clear data parameter tells the debugger whether or not it should 
clear out the previously collected data. The clear dataparameter can have one 
of these values: 


0 The profiler will continue to collect data (adding it to the existing 
data for the profiled areas) and to use the previous internal profile 
stacks. 0 is the default value. 


nonzero All previously collected profile data and internal profile stacks are 
cleared. 


The update rate parameter is the same as for the PF and PQ commands. 


Viewing Profile Data 


12.6 Viewing Profile Data 


The statistics collected during a profiling session are displayed in the 
PROFILE window. Figure 12-1 shows an example of this window. 


Figure 12-1. An Example of the PROFILE Window 


profile data 
PROFILE = = A 
Area Name Count Inclusive Incl-Max Exclusive Excl-Max 
AR 00£00001-00£00008 et 65 65 19 19 
profile < CL <sample>#58 1 50 50 7 7 
areas CR <sample>#59-64 1 87 87 44 44 
CF call() 24 1623 99 1089 55) 
AL meminit 1 3 3 Z any 
AL 00£00059 disabled 


The example in Figure 12-1 shows the PROFILE window with some default 
conditions: 


[_] Column headings show the labels for the default set of profile data, 
including Count, Inclusive, Incl-Max, Exclusive, and Excl-Max. 


[_] The data is sorted on the address of the first line in each area. 


[] All marked areas are listed, including disabled areas. 


You can modify the PROFILE window to display selected profile areas or 
different data; you can also sort the data differently. The following subsections 
explain how to do these things. 


Note: 


To reset the PROFILE display back to its default characteristics, use 
View—Reset. 


| a) 


Viewing different profile data 


By default, the PROFILE window shows a set of statistics labeled as Count, 
Inclusive, Incl-Max, Exclusive, and Excl-Max. The Address field, which is not 
part of the default statistics, can also be displayed. Table 12-6 describes the 
statistic that each field represents. 
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Table 12-6. Types of Data Shown in the PROFILE Window 


Label 
Count 


Inclusive 


Incl-Max 
(inclusive maximum) 


Exclusive 


Excl-Max 
(exclusive maximum) 


Address 
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Profile data 
The number of times a profile area is entered during a session. 


The total execution time (cycle count) of a profile area, including the execution time 
of any subroutines called from within the profile area. 


The maximum inclusive time for one iteration of a profile area. 


If the profiled code contains no flow control (Such as conditional processing), inclu- 
sive-maximum will equal the inclusive timing divided by the count. 


The total execution time (cycle count) of a profile area, excluding the execution time 
of any subroutines called from within the profile area. 


In general, the exclusive data provides the best statistics for comparing the execution 
time of one profile area to another area. 


The maximum exclusive time for one iteration of a profile area. 


The memory address of the line. If the area is a function or range, the Address field 
shows the memory address of the first line in the area. 


In addition to viewing this data in the default manner, you can view each of 
these statistics individually. The benefit of viewing them individually is that in 
addition to a cycle count, you are also supplied with a percentage indication 
and a histogram. 


In order to view the fields individually, you can use the mouse—just point to the 
header line in the PROFILE window and click a mouse button. You can also 
use the View—>Data menu to select the field you’d like to display. When you 
use the left mouse button to click on the header, fields are displayed individual- 
ly in the order listed below on the left. (Use the right mouse button to go in the 
opposite direction.) On the right are the corresponding menu selections. 


count View—Data —Count 

Inclusive Inclusive 

Ine ses —+Inclusive Max 
eel —Exclusive 
Eel aer: —Exclusive Max 
Address —Address 

| 
Default >All 


One advantage of using the mouse is that you can change the display while 
you're profiling. 


Data accuracy 


Sorting profile data 


Viewing Profile Data 


During a profiling session, the debugger sets many internal breakpoints and 
issues a series of RUNB commands. As a result, the processor is momentarily 
halted when entering and exiting profiling areas. This stopping and starting 
can affect the cycle count information (due to pipeline flushing and the me- 
chanics of software breakpoints) so that it varies from session to session. This 
method of profiling is referred to as intrusive profiling. 


Treat the data as relative, not absolute. The percentages and histograms are 
relevant only to the cycle count from the starting point to the stopping 
point—not to overall performance. Even though the cycle counts may change 
if you profiled the same area twice, the relationship of that area to other profiled 
areas should not change. 


By default, the data displayed in the PROFILE window is sorted according to 
the memory addresses of the displayed areas. The area with the least signifi- 
cant address is listed first, followed by the area with the most significant ad- 
dress, etc. When you view fields individually, the data is automatically sorted 
from highest cycle count to lowest (instead of by address). 


You can sort the data on any of the data fields by using the View—Sort menu. 
For example, to sort all the data on the basis of the values of the Inclusive field, 
use View—Sort—Inclusive; the area with the highest Count field will display 
first, and the area with the lowest Count field will display last. This applies even 
when you are viewing individual fields. 


Viewing different profile areas 


By default, all marked areas are listed in the PROFILE window. You can modify 
the window to display selected areas. To do this, use the selections on the 
View—>Filter pulldown menu; these selections are summarized in Table 12-7. 
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Table 12—7.Menu Selections for Displaying Areas in the PROFILE Window 


To view these areas 

Lines 

(] By line number 

(J All lines in a function 

_] All lines in a module 

_} All lines everywhere 
Ranges 

(J By line numbers 

(] All ranges in a function 
(] All ranges in a module 
_] All ranges everywhere 
Functions 

(} By function name 

(] All functions in a module 
_] All functions everywhere 
All areas 

_] All areas in a function 


(] All areas in a module 


(] All areas everywhere 


C only: 
View->Filter>C level 


—Line areas 
Explicitly 
in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
in one Function 
in one Module 
Globally 
—Function areas 
Explicitly 
—in one Module 
Globally 
—Range areas 
in one Function 
—in one Module 


Globally 


Interpreting session data 


Disassembly only: 
View—Filter->Asm level 


—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 
—Range areas 
Explicitly 
—in one Function 
—in one Module 


Globally 


not applicable 


—Range areas 
—in one Function 
—in one Module 


Globally 


C and disassembly: 
View->Filter—Both levels 


—Line areas 
not applicable 
—in one Function 
—in one Module 
—Globally 
—Range areas 
not applicable 
in one Function 
—in one Module 
Globally 
—Function areas 
not applicable 
—in one Module 
Globally 
—Range areas 
—in one Function 
—in one Module 


—Globally 


General information about a profiling session is displayed in the COMMAND 
window during and after the session. This information identifies the starting 
and stopping points. It also lists statistics for three important areas: 


LJ 


J 
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Run cycles shows the number of execution cycles consumed by the 
program from the starting point to the stopping point. 


Profile cycles equals the run cycles minus the cycles consumed by 


disabled areas. 


Hits shows the number of internal breakpoints encountered during the 


profiling session. 


Viewing Profile Data 


Viewing code associated with a profile area 


H 


You can view the code associated with a displayed profile area. The debugger 
will update the display so that the associated C or disassembly statements are 
shown in the FILE or DISASSEMBLY windows. 


Use the mouse to select the profile area in the PROFILE window and display 
the associated code: 


1) Point to the appropriate area name in the PROFILE window. 


2) Click the right mouse button. 


The area name and the associated C or disassembly statement will be 
highlighted. To view the code associated with another area, point and click 
again. 


If you are attempting to show disassembly, you may have to make several 
attempts because program memory can be accessed only when the target is 
not running. 
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12.7 Saving Profile Data to a File 


oe 
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vaa 


You may want to run several profiling sessions during a debugging session. 
Whenever you start a new profiling session,the results of the previous session 
are lost. However, you can save the results of the current profiling session to 
a system file. You can use two commands to do this: 


To save the contents of the PROFILE window to a system file, use the VAC 
(view save current) command. The syntax for this command is: 


vac filename 


This saves only the current view; if, for example, you are viewing only the 
Count field, then only that information will be saved. 


To save all data for the currently displayed areas, use the VAA (view save all) 
command. The syntax for this command is: 


vaa_ filename 


This saves all views of the data—including the individual count, inclusive, 
etc.—with the percentage indications and histograms. 


Both commands write profile data to filename. The filename can include path 
information. There is no default filename. If filename already exists, the 
command will overwrite the file with the new data. 


Note that if the PROFILE window displays only a subset of the areas that are 
marked for profiling, data is saved only for those areas that are displayed. (For 
VAC, the currently displayed data will be saved for the displayed areas. For 
VAA, all data will be saved for the displayed areas.) If some areas are hidden 
and you want to save all the data, be sure to select View—Reset before saving 
the data to a file. 


The file contents are in ASCII and are formatted in exactly the same manner 
as they are displayed (or would be displayed) in the PROFILE window. The 
general profiling-session information that is displayed in the COMMAND 
window is also written to the file. 
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Summary of Commands 
and Special Keys 


This chapter summarizes the basic debugger, profiling, and parallel debug 
manager (PDM) commands and the debugger’s special key sequences. 
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Editing text on the command line 13-67 
Using the command history 13-67 
Switching modes 13-68 
Halting or escaping from an action 13-68 
Displaying pulldown menus 13-68 
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Selecting or closing a window 13-69 
Moving or sizing a window 13-69 
Scrolling through a window’s contents 13-70 
Editing data or selecting the active field 13-70 
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13.1 Functional Summary of Debugger Commands 
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This section summarizes the debugger commands according to these catego- 
ries: 


I 


Managing multiple debuggers. These commands allow you to group 
debuggers, run code on multiple processors, and send commands to a 
group of debuggers. 


Changing modes. These commands enable you to switch freely between 
the three debugging modes (auto, mixed, and assembly). You can select 
these commands from the Mode pulldown menu, also. 


Managing windows. These commands enable you to select the active 
window and move or resize the active window. You can perform these 
functions with the mouse, also. 


Displaying and changing data. These commands enable you to display 
and evaluate a variety of data items. Some of these commands are 
available on the Watch pulldown menu, also. 


Performing system tasks. These commands enable you to perform sev- 
eral DOS-like functions and provide you with some control over the target 
system. 


Displaying files and loading programs. These commands enable you 
to change the displays in the FILE and DISASSEMBLY windows and to 
load object files into memory. Several of these commands are available 
on the Load pulldown menu. 


Managing breakpoints. These commands provide you with a command 
line method for controlling software breakpoints and are also available 
through the Break pulldown menu. You can also set/clear breakpoints in- 
teractively. 


Customizing the screen. These commands allow you to customize the 
debugger display, then save and later reuse the customized displays. You 
can also use the Color pulldown menu to access these commands. 


Memory mapping. These commands enable you to define the areas of 
target memory that the debugger can access. You can also use the 
Memory pulldown menu to access these commands. 


Running programs. These commands provide you with a variety of 
methods for running your programs in the debugger environment. The 
basic run and single-step commands are available on the menu bar, also. 


Profiling commands. These commands enable you to collect execution 
statistics for your code. Commands can be entered from the pulldown 
menus or on the command line. 
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Managing multiple debuggers 


Use this See 
To do this command page 
Assign a variable to the result of an expression @ 13-13 
Use the command history | 13-13 
Define a custom command string alias 13-15 
Record the information shown in the PDM display dlog 13-23 
area 
Display a string to the PDM display area echo 13-24 
Evaluate an expression in a debugger or group of eval 13-25 
debuggers and set a variable to the result 
List available PDM commands help 13-28 
View the description of a PDM command help 13-28 
List the last twenty commands history 13-28 
Conditionally execute PDM commands if/elif/else/endif 13-29 
Loop through PDM commands loop/break/con- ~—- 13-311 

tinue/endloop 
Pause the PDM pause 13-40 
Halt code execution pesc 13-40 
Global halt phalt 13-41 
Run code globally prun 13-44 
Run free globally prunf 13-44 
Single-step globally pstep 13-45 
Exit any debugger and/or the PDM quit 13-45 
Send a command to an individual processor or a send 13-50 
group of processors 
Change the PDM prompt set 13-51 
Create your own system variables set 13-51 
Define or modify a group of processors set 13-51 
List all system variables or groups of processors set 13-51 
Set the default group set 13-51 
Invoke an individual debugger spawn 13-55 
Find the execution status of a processor or a group stat 13-56 
of processors 
Enter an operating-system command system 13-57 
Execute a batch file take 13-58 
Delete an alias definition unalias 13-58 
Delete a group or system variable unset 13-59 
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Changing modes 


Managing windows 


Displaying and changing data 
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Use this 
To do this command See page 
Put the debugger in assembly mode asm 13-15 
Put the debugger in auto mode for debugging Cc 13-18 
code 
Put the debugger in mixed mode mix 13-37 
Use this 
To do this command See page 
Reposition the active window move 13-38 
Resize the active window size 13-53 
Select the active window win 13-62 
Make the active window as large as possible zoom 13-63 
Use this 
To do this command See page 
Evaluate and display the result of a C expression ? 13-12 
Display the values in an array or structure ordisplay disp 13-22 
the value that a pointer is pointing to 
Evaluate a C expression without displaying the eval 13-25 
results 
Display a different range of memory inthe MEMORY mem 13-35 
window 
Display a pop-up MEMORY window mem1,mem2, 13-35 
mem3 
Change the default format for displaying datavalues __ setf 13-52 
Continuously display the value of a variable, regis- wa 13-61 
ter, or memory location within the WATCH window 
Delete a data item from the WATCH window wd 13-62 
Delete all data items from the WATCH window and wr 13-63 
close the WATCH window 
Show the type of a data item whatis 13-62 
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Performing system tasks 


Use this 
To do this command See page 
Define your own command string alias 13-15 
Change the current working directory from withinthe — cd/chdir 13-18 
debugger environment 
Clear all displayed information fromthe COMMAND cls 13-19 
window display area 
List the contents of the currentdirectory or any other — dir 13-21 
directory 
Record the information shown in the COMMAND — dlog 13-23 
window display area 
Display a string to the COMMAND window while echo 13-24 
executing a batch file 
Conditionally execute debugger commands in a _ if/else/endif 13-30 
batch file 
Loop debugger commands in a batch file loop/endloop = =13-32 
Exit the debugger quit 13-45 
Reset the target system (emulator only), the simula- _ reset 13-46 
tor, or the EVM 
Associate a beeping sound with the display of error sound 13-54 
messages 
Enter any operating-system command or exittoa system 13-57 
system shell 
Execute commands from a batch file take 13-58 
Delete an alias definition unalias 13-58 
Name additional directories that can be searched use 13-59 


when you load source files 
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Displaying files and loading programs 


Managing breakpoints 


Customizing the screen 
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Use this 
To do this command See page 
Display C and/or assembly language code at a_ addr 13-14 
specific point 
Reopen the CALLS window calls 13-18 
Display assembly language code at a specific dasm 13-21 
address 
Display a text file in the FILE window file 13-26 
Display a specific C function func 13-27 
Load an object file load 13-30 
Modify disassembly with the patch assembler patch 13-40 
Load only the object-code portion of an object file reload 13-46 
Load only the symbol-table portion of an object file § sload 13-54 
Use this 
To do this command See page 
Add a software breakpoint ba 13-16 
Delete a software breakpoint bd 13-16 
Display a list of all the software breakpoints that are bl 13-16 
set 
Reset (delete) all software breakpoints br 13-17 
Use this 
To do this command See page 
Change the border style of any window border 13-17 
Change the screen colors, but don’t update the color 13-19 
screen immediately 
Change the command-line prompt prompt 13-43 
Change the screen colors and update the screen _ scolor 13-49 
immediately 
Load and use a previously saved custom screen _ sconfig 13-50 
configuration 
Save a custom screen configuration ssave 13-55 
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Memory mapping 
Use this 
To do this command See page 
Initialize a block of memory fill 13-26 
Add an address range to the memory map ma 13-32 
Enable or disable memory mapping map 13-33 
Connect a simulated I/O port to an input or output file mc 13-34 
(simulator only) 
Delete an address range from the memory map md 13-35 
Disconnect a simulated |/O port (simulator only) mi 13-36 
Display a list of the current memory map settings ml 13-37 
Reset the memory map (delete all ranges) mr 13-38 
Save a block of memory to a system file ms 13-39 
Connect an input file to the pin pinc 13-42 
Disconnect the input file from the pin pind 13-42 
List the pins that are connected to the input files pinl 13-42 
Running programs 
Use this 
To do this command See page 
Single-step through assembly language or C code, —_—cnext 13-19 
one C statement at a time; step over function calls 
Single-step through assembly language or C code, __—cstep 13-20 
one C statement at a time 
Run a program up to a certain point go 13-27 
Single-step through assembly language or C code; _—next 13-39 
step over function calls 
Reset the target system (emulator only), simulator, reset 13-46 
or EVM 
Reset the program entry point restart 13-46 
Execute code in a function and return to the func- return 13-47 
tion’s caller 
Run a program run 13-47 
Runa program with benchmarking—countthe num- —_runb 13-48 
ber of CPU clock cycles consumed by the executing 
portion of code 
Disconnect the emulator from the target system and __runf 13-48 
run free (emulator and EVM only) 
Single-step through assembly language or C code __ step 13-56 
Execute commands from a batch file take 13-58 


Summary of Commands and Special Keys 13-7 


Functional Summary of Debugger Commands 


Profiling commands 
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All of the profiling commands can be entered from the pulldown menus. In 
many cases, using the pulldown menus is the easiest way to use some of these 
commands. For this reason and also because there are over 100 profiling 
commands, most of these commands are not described individually in this 
chapter (as the basic debugger commands are). 


Listed below are some of the profiling commands that you might choose to 
enter from the command line instead of from a menu; these commands are 
also described in the alphabetical command summary. The remaining profiling 
commands are summarized in Section 13.4 on page 13-64. 


Use this 
To do this command See page 
Run a full profiling session pf 13-41 
Run a quick profiling session pq 13-43 
Resume a profiling session pr 13-43 
Add a stopping point sa 13-48 
Delete a stopping point sd 13-50 
List all the stopping points sl 13-54 
Delete all the stopping points sr 13-55 
Save all the profile data to a file vaa 13-59 
Save currently displayed profile data to a file vac 13-60 
Reset the display in the PROFILE window to show _ vr 13-60 


all areas and the default set of data 
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13.2 How the Menu Selections Correspond to Commands 


The following sample screens illustrate the relationship of the basic debugger 
commands to the menu bar and pulldown menus. 


Remember, you can use the menus with or without a mouse. To access a menu 
from the keyboard, press the key and the letter that’s highlighted in the 
menu name. (For example, to display the Load menu, press @.) Then, 
to make a selection from the menu, press the letter that’s highlighted in the 
command you've selected. (For example, on the Load menu, to execute Fle, 
press ©).) If you don’t want to execute a command, press to close the 
menu. 


Te | 


Note: 


Because the profiling environment supports over 100 profile-specific com- 
mands, it’s not practical to show the commands associated with the profile 
menu choices. 


Program-execution commands 


RUN command 
(without a parameter) 


STEP command 
(without a parameter) 


NEXT command 
(without a parameter) 


Run=F5 — 
Step=F8 a 


Next=F10 — 


File/load commands 


Toad LOAD command 
Hood RELOAD command 
Reload 

Symbols SLOAD command 
REstart RESTART command 
poese RESET command 


File 


FILE command 
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How the Menu Selections Correspond to Commands 


Breakpoint commands 


Watch commands 


BA command 


BD command 


BR command 


BL command 
Watch WA command 
Add 
Delete WD command 


Reset 


WR command 


Memory commands 


Se MA command 
Memory 
Add 


— Sen MD command 
Delete 


_| MR command 
Reset = 


List ML command 
Enable 7)... 

MAP command 
Fill 1. ——_ FILL command 


Save — ——E—ES—————— rrr 


Cone 
DisComr | as MC command 


MS command 


MI command 
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Screen-configuration commands 


SCONFIG command 
SSAVE command 

SCOLOR command 
BORDER command 
PROMPT command 


Mode commands 


C command 


ASM command 


MIX command 


Interrupt-simulation commands 


Pin PINC command 
Connect 
Disconnect PIND command 
List 
PINL command 


Analysis menu 


The Analysis pulldown menu does not correspond to specific debugger com- 
mands. Instead, the selections on this menu enable and disable the interface, 
as well as open dialog boxes that control the interface. Here are the functions 
of the Analysis menu selections. 


: Enable/Disable analysis interface 
Analysis 


Open the Count dialog box 
Open the Break dialog box 


Open the Emulator Pins dialog box 


Open the Analysis window 
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2 Alphabetical Summary of Debugger and PDM Commands 


13.3 Alphabetical Summary of Debugger and PDM Commands 


Syntax 
Menu selection 


Environments 


Description 
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Most of the commands can be used in the basic debugger environment and/or 
the profiling environment. Other commands can be used only by the parallel 
debug manager (PDM). A few commands can be used in two or more environ- 
ments. Each command description identifies the applicable environments for 
the command. 


Commands are not case sensitive; to emphasize this, command names are 
shown in both uppercase and lowercase throughout this book. 


Evaluate Expression 


2 expression [, display format 


none 


basic debugger [J PDM profiling 


The ? (evaluate expression) command evaluates an expression and shows 
the result in the COMMAND window display area. The expression can be any 
C expression, including an expression with side effects; however, you cannot 
use astring constant or function call in the expression. lf the expression identi- 
fies an address, you can follow it with @prog to identify program memory or 
@data to identify data memory. Without the suffix, the debugger treats an ad- 
dress expression as a program-memory location. 


If the result of expression is not an array or structure, then the debugger 
displays the results in the COMMAND window. If expression is a structure or 
array, ? displays the entire contents of the structure or array; you can halt long 
listings by pressing (sc). 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


: Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands !, @ 


Use the PDM Command History 


'{prompt number | string} 
Y" 


none 


L] basic debugger PDM (ei) profiling 


The PDM supports a command history that is similar to the UNIX command 
history. The PDM prompt identifies the number of the current command. This 
number is incremented with every command. The PDM command history al- 
lows you to re-enter any of the last twenty commands. 


[|_| The number parameter is the number of the PDM prompt that contains the 
command that you want to re-enter. 


_] The string parameter tells the PDM to execute the last command that be- 
gan with string. 


_} The !! command tells the PDM to execute the last command that you en- 
tered. 


Substitute Result of an Expression 


@ variable name = expression 


none 


L] basic debugger PDM e profiling 


Unlike the SET command, the @ command first evaluates the expression, and 
then sets the variable name to the result. The expression can be any expres- 
sion that uses the symbols described in Section 2.7, page 2-17. The variable 
name can consist of up to 128 alphanumeric characters or underscore charac- 
ters. 
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addr Alphabetical Summary of Debugger and PDM Commands 


ECC Display Code at Specified Address 


Syntax 


Menu selection 


Environments 


Description 
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addr address[@prog | @data | @io] 
addr function name 


none 


basic debugger a PDM LJ profiling 


Use the ADDR command to display C code or the disassembly at a specific 
point. ADDR’s behavior changes, depending on the current debugging mode: 


(_] In assembly mode, ADDR works like the DASM command, positioning the 
code starting at address or at function name as the first line of code in the 
DISASSEMBLY window. 


[_] In aC display, ADDR works like the FUNC command, displaying the code 
starting at address or at function name in the FILE window. 


[_] In mixed mode, ADDR affects both the DISASSEMBLY and FILE win- 
dows. 


By default, the address parameter is treated as a program-memory address. 
However, you can follow it with @prog to identify program memory or with 
@data to identify data memory. If you are using an emulator or EVM you can 
follow address with @io to identify I/O space. 


Note: 


ADDR affects the FILE window only if the specified addressis in a C function. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands alias, asm 


Define Custom Command String 


alias [alias name [, command string” | | 


none 


basic debugger PDM profiling 


You can use the ALIAS command to define customized command strings for 
the debugger or for the PDM: 


(_] The debugger version of the ALIAS command allows you to associate one 
or more debugger commands with a single alias name. 


(_] The PDM version of the ALIAS command allows you to associate one or 
more PDM commands with a single alias name or associate one or more 
debugger commands with a single alias name. 


You can include as many commands in the command string as you like, as long 
you separate them with semicolons and enclose the entire string of commands 
in quotation marks. You can also identify command parameters by a percent 
sign followed by a number (%1, %2, etc.). The total number of characters for 
an individual command (expanded to include parameter values) is limited to 
132 (this restriction applies to the debugger version of the ALIAS command 
only). 


Previously defined alias names can be included as part of the definition for a 
new alias. 


To find the current definition of an alias, enter the ALIAS command with the 
alias name only. To see a list of all defined aliases, enter the ALIAS command 
with no parameters. 


Enter Assembly Mode 


asm 


MoDe-Asm 
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The ASM command changes from the current debugging mode to assembly 
mode. If you’re already in assembly mode, the ASM command has no effect. 
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ba, bd, bl 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger and PDM Commands 


Add Software Breakpoint 


ba address 


Break—>Add 


basic debugger LJ PDM LJ profiling 


The BA command sets a software breakpoint at a specific address. This com- 
mand is useful because it doesn’t require you to search through code to find 
the desired line. The address can be an absolute address, any C expression, 
the name of a C function, or the name of an assembly language label. 


Breakpoints can be set in program memory (RAM) only; the address parame- 
ter is treated as a program-memory address. 


Delete Software Breakpoint 


bd address 


Break—> Delete 


basic debugger LJ PDM LJ profiling 


The BD command clears a software breakpoint at a specific address. The ad- 
dresscan be an absolute address, any C expression, the name of a C function, 
or the name of an assembly language label. The address is treated as a pro- 
gram-memory address. 


List Software Breakpoints 


bl 


Break-List 
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The BL command provides an easy way to get a complete listing of all the soft- 
ware breakpoints that are currently set in your program. It displays a table of 
breakpoints in the COMMAND window display area. BL lists all the break- 
points that are set, in the order in which you set them. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands’ border, br 


Change Style of Window Border 


border [active window style] [, [ inactive window style] [,resize window style]| 


Color—>Border 


basic debugger LJ PDM LJ profiling 


The BORDER command changes the border style of the active window, the 
inactive windows, and the border style of any window that you’re resizing. The 
debugger supports nine border styles. Each parameter for the BORDER 
command must be one of the numbers that identify these styles: 


Index Style 

Double-lined box 

Single-lined box 

Solid 1/2-tone top, double-lined sides/bottom 
Solid 1/4-tone top, double-lined sides/bottom 
Solid box, thin border 

Solid box, heavy sides, thin top/bottom 

Solid box, heavy borders 

Solid 1/2-tone box 

Solid 1/4-tone box 


ON Oak WOM + CO 


Note that you can execute the BORDER command as the Border selection on 
the Color pulldown menu. The debugger displays a dialog box so that you can 
enter the parameter values; in the dialog box, active window style is called 
foreground, and inactive window style is called background. 


Reset Software Breakpoint 


br 
Break—Reset 
basic debugger LJ PDM L] profiling 


The BR command clears all software breakpoints that are set. 
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c, calls, cd, chdir 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger and PDM Commands 


Enter Auto Mode 


c 


MoDe->C (auto) 
basic debugger L] PDM LJ profiling 


The C command changes from the current debugging mode to auto mode. If 
you're already in auto mode, then the C command has no effect. 


Open CALLS Window 


calls 


none 
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The CALLS command displays the CALLS window. The debugger displays 
this window automatically when you are in auto/C or mixed mode. However, 
you can close the CALLS window; the CALLS command opens the window 
again. 


Change Directory 


cd [directory name] 
chdir [directory name] 


none 


basic debugger LJ PDM profiling 


The CD or CHDIR command changes the current working directory from within 
the debugger. You can use relative pathnames as part of the directory name. 
If you don’tuse a pathname, the CD command displays the name of the current 
directory. Note that this command can affect any other command whose 
parameter is a filename, such as the FILE, LOAD, and TAKE commands, when 
used with the USE command. You can also use the CD command to change 
the current drive. For example, 

cd c: 


cd d:\csource 
ed c:\c5xhll 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Clear Screen 


cls 


none 


basic debugger LJ PDM profiling 


The CLS command clears all displayed information from the COMMAND 
window display area. 


Single-Step C, Next Statement 


cnext [expression] 


Next=F10 (in C code) 
basic debugger al PDM LJ profiling 


The CNEXT command is similar to the CSTEP command. It runs a program 
one C statement at a time, updating the display after executing each state- 
ment. If you’re using CNEXT to step through assembly language code, the 
debugger won’t update the display until it has executed all assembly language 
statements associated with a single C statement. Unlike CSTEP, CNEXT 
steps over function calls rather than stepping into them—you don’t see the 
single-step execution of the function call. 


The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional 
single-step execution (Running code conditionally, page 7-17, discusses this 
in detail). 


Change Screen Colors 


color area name, attribute, [, attributes [,attribute3 [,attribute,] | | 


none 


basic debugger LJ PDM LJ profiling 


The COLOR command changes the color of specified areas of the debugger 
display. COLOR doesn’t update the display; the changes take effect when 
another command, such as SCOLOR, updates the display. The area name 
parameter identifies the areas of the display that are affected. The attributes 
identify how the areas are affected. The first two attribute parameters usually 
specify the foreground and background colors for the area. If you do not supply 
a background color, the debugger uses black as the background. 
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color, cstep Alphabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 
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Valid values for the attribute parameters include: 


black blue green cyan 
red magenta yellow white 
bright blink 


Valid values for the area name parameters include: 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify the attribute. If you supply ambiguous aftrib- 
ute names, the debugger interprets the names in this order: black, blue, bright, 
blink. If you supply ambiguous area names, the debugger interprets them in 
the order that they’re listed above (left to right, top to bottom). 


Single-Step C 


cstep [expression] 
Step=F8 (in C code) 
basic debugger L] PDM L] profiling 


The CSTEP single-steps through a program one C statement at a time, 
updating the display after executing each statement. If you’re using CSTEP 
to step through assembly language code, the debugger won’t update the dis- 
play until it has executed all assembly language statements associated with 
a single C statement. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands__cstep, dasm, dir 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug op- 
tion). When function execution completes, single-step execution returns to the 
caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 


The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional 


single-step execution (Running code conditionally, page 7-17, discusses this 
in detail). 


Display Disassembly at Specified Address 


dasm_ address[@prog | @data] 
dasm_ function name 


none 
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The DASM command displays code beginning at a specific point within the 
DISASSEMBLY window. By default, the address parameter is treated as a 
program-memory address. However, you can follow it with @prog to identify 
program memory or with @data to identify data memory. 


List Directory Contents 


dir [directory name] 


none 
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The DIR command displays a directory listing in the display area of the 
COMMAND window. If you use the optional directory name parameter, the 
debugger displays a list of the specified directory’s contents. If you don’t use 
the parameter, the debugger lists the contents of the current directory. 
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disp Alphabetical Summary of Debugger and PDM Commands 


Syntax 
Menu selection 


Environments 
Description 
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Open DISP Window 


disp expression [, display format| 
none 
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The DISP command opens a DISP window to display the contents of an array, 
structure, or pointer expressions to a scalar type (of the form *pointer). If the 
expression is not one of these types, then DISP acts like a ? command. If the 
expression identifies an address, you can follow it with @prog to identify 
program memory or @data to identify data memory. If you are using an emula- 
tor or EVM, you can follow an address with @io to identify I/O space. Without 
the suffix, the debugger treats an address expression as a program-memory 
location. 


Once you open a DISP window, you may find that a displayed member is itself 
an array, structure, or pointer: 


A member that is an array looks like this [.. .] 
A member that is a structure looks like this {.. .} 
A member that is a pointer looks like an address 0x0000 


You can display the additional data (the data pointed to or the members of the 
array or structure) in another DISP window by using the DISP command again, 
using the arrow keys to select the field and then pressing (3), or pointing the 
mouse cursor to the field and pressing the left mouse button. You can have up 
to 120 DISP windows open at the same time. 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


* Default for the data type fo) Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


The display format parameter can be used only when you are displaying a 
scalar type, an array of scalar type, or an individual member of an aggregate 
type. 

You can also use the DISP command with a typecast expression to display 
memory contents in any format. Here are some examples: 

disp *0 

disp *(float *)123 

disp *(char *)0x111 


Syntax 


Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands disp, dlog 


This shows memory in the DISP window as an array of locations; the location 
that you specify with the expression parameter is member [0], and all other 
locations are offset from that location. 


Record Display Window 


dlog filename [,{a | w}] 


or 


dlog close 


none 
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The DLOG command allows you to record the information displayed in the 
COMMAND window or in the PDM display area into a log file. 


I 


To begin recording the information shown in the display area of the 
COMMAND window or in the display area of the PDM, use: 


dlog filename 


Log files can be executed with the TAKE command. When you use DLOG 
to record the information from the display area into a log file called file- 
name, the debugger (or PDM) automatically precedes all error or progress 
messages and command results with a semicolon to turn them into com- 
ments. This way, you can easily re-execute the commands in your log file 
by using the TAKE command. 


To end the recording session, enter: 


dlog close 


If necessary, you can write over existing log files or append additional informa- 
tion to existing files. The optional parameters of the DLOG command control 
how existing log files are used: 


LJ 


Appending to an existing file. Use the a parameter to open an existing 
file to which to append the information in the display area. 


Writing over an existing file. Use the w parameter to open an existing 
file to write over the current contents of the file. Note that this is the default 
action if you specify an existing filename without using either the a or w 
options; you will lose the contents of an existing file if you don’t use the 
append (a) option. 
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echo, elif, else, endif Alphabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 


Description 


Description 


Description 
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Echo String to Display Area 


echo _ string 


none 
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The ECHO command displays string in the display area of the COMMAND 
window or in the display area of the PDM. You can’t use quote marks around 
the string, and any leading blanks in your command string are removed when 
the ECHO command is executed. 


[_.] You can execute the debugger version of the ECHO command only ina 
batch file. 


[_.] You can execute the PDM version of the ECHO command in a batch file 
or from the command line. 


Test for Alternate Condition 


ELIF provides an alternative test by which you can execute PDM commands 
in the IF/ELIF/ELSE/ENDIF command sequence. See page 13-29 for more in- 
formation about these commands. 


Execute Alternative Commands 


ELSE provides an alternative list of debugger or PDM commands in the IF/ 
ELSE/ ENDIF or IF/ELIF/ELSE/ENDIF command sequences, respectively. 
See pages 13-30 and 13-29 for more information about these commands. 


Terminate Conditional Sequence 


ENDIF identifies the end of a conditional-execution command sequence 
begun with an IF command. See pages 13-29 and 13-30 for more information 
about these commands. 


Description 


eval 


Syntax 


Menu selection 


Environments 


Description 


WE] 


Syntax 
Menu selection 


Environments 


Description 
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Terminate Looping Sequence 


ENDLOOP identifies the end of the LOOP/ENDLOOP command sequence. 
See pages 13-31 and 13-32 for more information about the LOOP/ENDLOOP 
commands. 


Evaluate Expression 


eval expression[@prog | @data | @io] 
e expression|@prog | @data | @io] 


none 
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The EVAL command evaluates an expression like the ? command does but 
does not show the resultin the COMMAND window display area. EVAL is use- 
ful for assigning values to registers or memory locations in a batch file (where 
it’s not necessary to display the result). 


If the expression identifies an address, you can follow it with @prog to identify 
program memory or @data to identify data memory. If you are using an emula- 
tor or EVM you can follow an address with @io to identify I/O space. Without 
the suffix, the debugger treats an address expression as a program-memory 
location. 


Evaluate Expression and Set to Variable 


eval [-g {group | processor name}] variable name=expression|, format] 


none 
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The EVAL command evaluates an expression in a debugger and sets a vari- 
able to the result of the expression. 


[_] The -g option specifies the group or processor that EVAL should be sent 
to. If you don’t use this option, the command is sent to the default group 


(dgroup). 
(_} When you send the EVAL command to more than one processor, the PDM 
takes the variable name that you supply and appends a suffix for each pro- 


cessor. The suffix consists of the underscore character (_) followed by the 
name that you assigned the processor. 


Summary of Commands and Special Keys 13-25 


eval, file, fill Asohabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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[_] The expression can be any expression that uses the symbols described 
in Section 2.7, page 2-17. 


[_.} When you use the optional format parameter, the value that the variable 
is set to will be in one of the following formats: 


Parameter Result Parameter Result 


. Default for the data type oO Octal 
c ASCII character (bytes) p Valid address 
d Decimal s ASCII string 
e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 
Display Text File 
file filename 
Load->File 
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The FILE command displays the contents of any text file in the FILE window. 
The debugger continues to display this file until you run a program and halt in 
aC function. This command is intended primarily for displaying C source code. 
You can view only one text file at a time. 


You are restricted to displaying files that are 65,518 bytes long or less. 


Fill Memory 


fill address, page, length, data 
Memory-—Fill 
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The FILL command fills a block of memory with a specified value. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands fill, func, go 


[| The address parameter identifies the first address in the block. 


_] The page parameter is a one-digit number that identifies the type of 
memory (program or data) to fill: 


To fill this type of Use this value as the page 
memory parameter 

Program memory 0 

Data memory 1 

I/O space 2 (EVM and Emulator) 


Lu 


The /ength parameter defines the number of words to fill. 


[|_| The data parameter is the value that is placed in each word in the block. 


Display Function 
func function name 
func address 


none 
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The FUNC command displays a specified C function in the FILE window. You 
can identify the function by its name or its address; an address parameter is 
treated as a program-memory address. Note that FUNC works the same way 
FILE works, but with FUNC you don’t need to identify the name of the file that 
contains the function. 


Run to Specified Address 


go_ [address] 


none 
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The GO command executes code up to a specific point in your program. The 
address parameter is treated as a program-memory address. If you don’t 
supply an address, then GO acts like a RUN command without an expression 
parameter. 
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halt, help, history Alphabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Halt Target System Emulator & EVM Only 


halt 


none 
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The HALT command halts the target system after you’ve entered a RUNF 
command. When you invoke the debugger, it automatically executes a HALT 
command. Thus, if you enter a RUNF, quit the debugger, and later reinvoke 
the debugger, you will effectively reconnect the emulator to the target system 
and run the debugger in its normal mode of operation. 


List PDM Commands 
help [command] 
none 
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The HELP command provides a brief description of the requested PDM com- 
mand. If you omit the command parameter, the PDM lists all of the available 
PDM commands. 


LJ basic debugger 


List the Last Twenty PDM Commands 


history 


none 


PDM LJ profiling 


The HISTORY command displays the last twenty PDM commands that you’ve 
entered. 


LJ basic debugger 


if/elif/else/endif 


Syntax 


Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands _ if/elif/else/endif 


Conditionally Execute PDM Commands 


if expression 
PDM commands 
[elif expression 
PDM commands] 
[else 

PDM commands] 
endif 


none 
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These commands allow you to execute PDM commands conditionally in a 
batch file or from the command line. 


[_] If the expression for the IF is nonzero, the PDM executes all commands 
between the IF and ELIF, ELSE, or ENDIF. 


[_] The ELIF is optional. If the expression for the ELIF is nonzero, the PDM 
executes all commands between the ELIF and ELSE or ENDIF. 


[|_| The ELSE is optional. Ifthe expressions for the IF and ELIF (if present) are 
false (zero), the PDM executes the commands between the ELSE and 
ENDIF. 


The IF/ELIF/ELSE/ENDIF can be entered interactively or included in a batch 
file that is executed by the TAKE command. When you enter IF from the PDM 
command line, a question mark (?) prompts you for the next entry. The PDM 
continues to prompt you for input using the ? until you enter ENDIF. After you 
enter ENDIF, the PDM immediately executes the IF command. 


If you are in the middle of interactively entering an IF statement and want to 
abort it, type ©. 
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if/else/endif, load Alphabetical Summary of Debugger and PDM Commands 


if/else/endif Conditionally Execute Debugger Commands 
Syntax if expression 
debugger commands 
[else 
debugger commands] 
endif 
Menu selection none 
Environments basic debugger LJ PDM profiling 
Description These commands allow you to execute debugger commands conditionally in 


a batch file. If the expression if nonzero, the debugger executes the com- 
mands between the IF and the ELSE or ENDIF. Note that the ELSE portion of 
the command sequence is optional. 


You can substitute a keyword for the expression. Keywords evaluate to true 
(1) or false (0). You can use the following keywords with the IF command: 


_] $$EMU$$ (tests for the emulator version of the debugger) 
_] $$SIM$$ (tests for the simulator version of the debugger) 
_] $$EVM$$ (tests for the EVM version of the debugger) 


The conditional commands work with the following provisions: 


[_] You can use conditional commands only in a batch file. 
[_] You must enter each debugger command on a separate line in the file. 
[.} You can’t nest conditional commands within the same batch file. 


Ce «= Load Executable Object File 


Syntax load object filename 

Menu selection Load— Load 

Environments basic debugger LJ PDM profiling 
Description The LOAD command loads both an object file and its associated symbol table 


into memory. In effect, the LOAD command performs both a RELOAD and an 
SLOAD. If you don’t supply an extension, the debugger looks for filename.out. 
Note that the LOAD command clears the old symbol table and closes the 
WATCH and DISP windows. 
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Alphabetical Summary of Debugger and PDM Commands__loop/break/continue/endloop 


oXe) of o) gt: 1.4 
exo) at italec=ycvare| Lele) e) 


Syntax 


Menu selection 


Environments 


Description 


Loop Through PDM Commands 


loop Boolean expression 
PDM commands 

[break] 

[continue] 

endloop 


none 
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The LOOP/BREAK/CONTINUE/ENDLOOP commands allow you to set up a 
looping situation in a batch file or from the command line. Unlike the debugger 
version of the LOOP/ENDLOOP commands, the PDM version of the LOOP 
command evaluates only Boolean expressions: 


[_] Ifthe Boolean expression evaluates to true (1), the PDM executes all com- 
mands between the LOOP and BREAK, CONTINUE, or ENDLOOP. 


[_] If the Boolean expression evaluates to false (0), the loop is not entered. 


The optional BREAK command allows you to exit the loop without having to 
reach the ENDLOOP. This is helpful when you are testing a group of proces- 
sors and want to exit if an error is detected. 


The CONTINUE command, which is also optional, acts as a goto and returns 
command flow to the enclosing LOOP command. CONTINUE is useful when 
the part of the loop that follows is complicated; returning to the top of the loop 
avoids further nesting. 


The LOOP/BREAK/CONTINUE/ENDLOOP commands can be entered inter- 
actively or included in a batch file that is executed by the TAKE command. 
When you enter LOOP from the PDM command line, a question mark (?) 
prompts you for the next entry. The PDM continues to prompt you for input us- 
ing the ? until you enter ENDLOOP. After you enter ENDLOOP, the PDM im- 
mediately executes the LOOP command. 


If you are in the middle of interactively entering an LOOP statement and want 
to abort it, type ©). 
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CoXe) oyf=F ale | Coxe) e) Loop Through Debugger Commands 
Syntax loop expression 
debugger commands 
endloop 
Menu selection none 
Environments basic debugger LJ PDM profiling 
Description The LOOP/ENDLOOP commands allow you to set up a looping situation in a 


batch file. These looping commands evaluate in the same method as in the run 
conditional command expression: 


[_] If you use an expression that is not Boolean, the debugger evaluates the 
expression as a loop count. 


[_] If you use a Boolean expression, the debugger executes the command 
repeatedly as long as the expression is true. 


The LOOP/ENDLOOP commands work under the following conditions: 


[| You can use LOOP/ENDLOOP commands only in a batch file. 
[_] You must enter each debugger command on a separate line in the file. 
[_.]} You can’t nest LOOP/ENDLOOP commands within the same file. 


CL Add Block to Memory Map 


Syntax ma address, page, length, type 

Menu selection Memory—Add 

Environments basic debugger LJ PDM profiling 
Description The MA command identifies valid ranges of target memory. Note that a new 


memory map must not overlap an existing entry; if you define a range that over- 
laps an existing range, the debugger ignores the new range. 


(_] The address parameter defines the starting address of a range in data or 


program memory. This parameter can be an absolute address, any C 
expression, the name of a C function, or an assembly language label. 
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Syntax 
Menu selection 
Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands ma, map 


(_] The page parameter is a one-digit number that identifies the type of 
memory (program, data, or I/O) that the range occupies: 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


_] The length parameter defines the length of the range. This parameter can 
be any C expression. 


[_] The type parameter identifies the read/write characteristics of the memory 
range. The type must be one of these keywords: 


Use this keyword as the type 


To identify this kind of memory, parameter 

Read-only memory R, ROM, or READONLY 
Write-only memory W, WOM, or WRITEONLY 
Read/write memory WR or RAM 

No-access memory PROTECT 

Input port IPORT 

Output port OPORT 

Input/output port IOPORT 


You can use the IPORT, OPORT, and IOPORT type parameters and the page 
2 parameter in conjunction with the MC command to simulate I/O ports. 


Enable Memory Mapping 


map {on | off} 


Memory—Enable 
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The MAP command enables or disables memory mapping. In some instances, 
you may want to explicitly enable or disable memory. Note that disabling 
memory mapping can cause bus fault problems in the target because the 
debugger may attempt to access nonexistent memory. 
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mc Alphabetical Summary of Debugger and PDM Commands 


Cia! §$§=Connect Simulated I/O Port to a File Simulator Only 


Syntax 


Menu selection 


Environments 


Description 
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mc_ port address, page, filename, {READ | WRITE} 


Memory—Connect 
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The MC command connects IPORT, OPORT, or IOPORT to an input or output 
file. Before you can connect the port, you must add it to the memory map with 
the MA command. 


(_} The port address parameter defines the address of the I/O port. This 
parameter can be an absolute address, any C expression, the name of a 
C function, or an assembly language label. 


_] The page parameter is a one-digit number that identifies the page that the 
port occupies. 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


[__] The filename parameter can be any filename. If you connect a port to read 
from a file, the file must exist or the MC command will fail. 


[|_| The final parameter is specified as READ or WRITE and defines how the 
file will be used (for input or output, respectively). 


The file is accessed during an IN or OUT instruction to the associated port 
address. Any port in I/O space can be connected to a file. A maximum of one 
input and one output file can be connected to a single port; multiple ports can 
be connected to a single file. Memory-mapped ports can also be connected 
to files; any instruction that reads or writes to the memory-mapped port will 
read or write to the associated file. 


This port-connect feature can also be used for some simulation of serial ports. 
The DXR, DRR, TDXR, and TRCV registers can be connected to files. Trans- 
mit interrupts are generated 32 or 64 cycles after every load of DXRand TDXR 
(based on the value of the FO bit in the SPCR, which determines whether the 
device is in word or byte mode). Receive interrupts are generated and the data 
is read from the input file every 32 or 64 cycles after the last read. Note that 
the TDM serial-port mode of serial port 2 is not implemented. The TSPC and 
SPC control registers bits are not implemented (except for the FO bit). 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Delete Block From Memory Map 


md_ address, page 


Memory—Delete 
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The MD command deletes a range of memory from the debugger’s memory 

map. 

_} The address parameter identifies the starting address of the range of 
program, data, or I/O memory. If you supply an address that is not the start- 
ing address of a range, the debugger displays this error message in the 
COMMAND window display area: 


Specified map not found 


J The page parameter is a one-digit number that identifies the type of 
memory (program, data, or I/O) that the range occupies: 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


TT | 


Note: 


If you want to use the MD command to remove a simulated I/O port, you must 
first disconnect the port with the MI command. 


Modify MEMORY Window Display 


mem|[#] expression |, display formal 


none 
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The MEM command identifies a new starting address for the block of memory 
displayed in the MEMORY window. The optional extension number (#) opens 
an additional MEMORY window, allowing you to view a separate block of 
memory. The debugger displays the contents of memory at expression in the 
first data position in the MEMORY window. The end of the range is defined by 
the size of the window. The expressioncan be an absolute address, a symbolic 
address, or any C expression. 
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mem, mi = Alphabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 
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You can display either program or data memory; or, if you are using an emula- 
tor or EVM, you can display I/O space: 


(_} By default, the MEMORY window displays data memory. Although it is not 
necessary, you can explicitly specify data memory by following the expres- 
sion parameter with a suffix of @data. 


(_} You can display the contents of program memory by following the expres- 
sion parameter with a suffix of @prog. When you do this, the MEMORY 
window’s label changes to MEMORY [PROG] so that there is no confusion 
about the type of memory being displayed. 


(_} Using an emulator or EVM, you can display the contents of the I/O space 
by following the expression parameter with a suffix of @io. When you do 
this, the MEMORY window’s label changes to MEMORY [IO] so that there 
is no confusion about the type of memory being displayed. 


When you use the optional display format parameter, memory will be dis- 
played in one of the following formats: 


Parameter Result Parameter Result 


: Default for the data type 

c ASCII character (bytes) oO Octal 

d Decimal p Valid address 

e Exponential floating point u Unsigned decimal 

f Decimal floating point x Hexadecimal 
Disconnect I/O Port Simulator Only 
mi_ port address, page, {READ | WRITE} 
Memory—>DisConn 
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The MI command disconnects a simulated I/O port from its associated system 
file. 


(_} The port address parameter identifies the address of the I/O port, which 
must have been previously defined with the MC command. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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(_] The page parameter is a one-digit number that identifies the type of 
memory (program, data, or I/O) that the port occupies: 


Use this value as the page 


To identify this page, parameter 
Program memory 0 
Data memory 1 
I/O space 2 


The page parameter for the MI command must match the page parameter 
that was used with the MC command to connect the port. 


Enter Mixed Mode 
mix 
MoDe->Mixed 


basic debugger LJ PDM LJ profiling 


The MIX command changes from the current debugging mode to mixed mode. 
If you’re already in mixed mode, the MIX command has no effect. 


List Memory Map 


ml 

Memory-—>List 
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The ML command lists the memory ranges that are defined for the debugger’s 


memory map. The ML command lists the starting address, ending address, 
and read/write characteristics of each defined memory range. 
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move 


Syntax 
Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Move Active Window 


move _[X position, Y position [, width, length ] | 
none 
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The MOVE command moves the active window to the specified XY position. 
If you choose, you can resize the window while you move it (see the SIZE 
command for valid width and /engthvalues). Youcan use the MOVE command 
in one of two ways: 


__} By supplying a specific X position and Y position or 
|_| By omitting the X position and Y position parameters and using function 
keys to interactively move the window. 


You can move a window by defining a new XY position for the window’s upper 
left corner. Valid X and Y positions depend on the screen size and the window 
size. X positions are valid if the X position plus the window width in characters 
is less than or equal to the screen width in characters. Y positions are valid if 
the Y position plus the widow height is less than or equal to the screen height 
in lines. 


For example, if the window is 10 characters wide and 5 lines high and the 
screen size is 80 x 25, the command move 70, 20 would put the lower right- 
hand corner of the window in the lower right-hand corner of the screen. No X 
value greater than 70 or Y value greater than 20 would be valid in this example. 


If you enter the MOVE command without X positionand Y positionparameters, 
you can use arrow keys to move the window. 


(3) Moves the active window down one line. 

an) Moves the active window up one line. 

Moves the active window left one character position. 
Moves the active window right one character position. 


When you're finished using the arrow keys, you must press or [2]. 


Reset Memory Map 


mr 


Memory—Reset 
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The MR command resets the debugger’s memory map by deleting all defined 
memory ranges from the map. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 
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Save Memory Block to File 


ms_ address, page, length, filename 


Memory—Save 
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The MS command saves the values in a block of memory to a system file; files 
are saved in COFF format. 


[_] The address parameter identifies the first address in the block. 


__] The page is a one-digit number that identifies the type of memory (pro- 
gram, data, or I/O) to save: 


To save this type of Use this value as the page 
memory parameter 

Program memory 0 

Data memory 1 

I/O space 2 (EVM and Emulator) 


_] The /ength parameter defines the length, in words, of the block. This pa- 
rameter can be any C expression. 


[__] The filename is a system file. If you don’t supply an extension, the debug- 
ger adds an .obj extension. 


Single-Step, Next Statement 


next [expression] 


Next=F10 (in disassembly) 
basic debugger el PDM LJ profiling 


The NEXT command is similar to the STEP command. If you're in C code, the 
debugger executes one C statement at a time. In assembly or mixed mode, 
the debugger executes one assembly language statement at a time. Unlike 
STEP, NEXT never updates the display when executing called functions; 
NEXT always steps to the next consecutive statement. Unlike STEP, NEXT 
steps over function calls rather than stepping into them—you don’t see the 
single-step execution of the function call. 


The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional 
single-step execution (Running code conditionally, page 7-17, discusses this 
in detail). 
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patch, pause, pesc 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger and PDM Commands 


Patch Assemble 


patch address, assembly language instruction 


none 
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The PATCH command allows you to patch-assemble disassembly state- 
ments. The address parameter identifies the address of the statement you 
want to change. The assembly language instruction parameter is the new 
statement you want to use at address. Note that patch assembly is available 
on all debugger platforms except DOS. 


Pause Execution 


pause 


none 
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The PAUSE command allows you to pause the debugger or PDM while run- 
ning a batch file or executing a flow control command. Pausing is especially 
helpful in debugging the commands in a batch file. 


When the debugger or PDM reads this command in a batch file or during a flow 
control command segment, the debugger/PDM stops execution and displays 
the following message: 


<< pause - type return >> 


To continue processing, press @). 


Send ESC Key to Debuggers 


pesc [-g {group | processor name}] 


none 
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The PESC command sends the key to an individual debugger or to a 
group of debuggers. PESC halts program execution, but all processors in a 
group don't halt at the same real time; individual processors halt in the order 
in which they were added to the group. 


The —g option identifies the group or processor that the command should be 
sent to. If you don't use this option, the key is sent to the default group 


(dgroup). 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Profile, Full 


pf starting point|, update rate] 


Profile—>Full 
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The PF command initiates a RUN and collects a full set of statistics on the 
defined areas between the starting point and the first-encountered stopping 
point. The starting point parameter can be a label, a function name, or a 
memory address. 


The optional update rate parameter determines how often the PROFILE 
window will be updated. The update rate parameter can have one of these 
values: 


Value Description 


0 This is the default. Statistics are not updated until the session is halted 
(although you can force an update by clicking the mouse in the window 
header). A “spinning wheel” character is shown to indicate that a profiling 
session is in progress. 


21 Statistics are updated during the session. A value of 1 means that data 
is updated as often as possible. 


<0 Statistics are not updated until the profiling session is halted, and the 
“spinning wheel” character is not displayed. 


Halt Processors in Parallel 


phalt [{-g group | processor name}] 


none 
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The PHALT command halts one or more processors. If you send a PRUN or 
PRUNF command to a group orto an individual processor, you can use PHALT 
to halt the group or the individual processor. Each processor in a group is 
halted at the same real time. If you don’t use the —g option to specify a group 
or a processor name, the PHALT command will be sent to the default group 
(dgroup). 
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pinc, pind, pinl 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Connect Pin Simulator Only 


pinc pinname, filename 


Pin—Connect 
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The PINC command connects an input file to interrupt pin. 


LJ profiling 


_] The pinname parameter identifies the interrupt pin and must be one of the 
five interrupt pins (INT1—INT4 or BIO). 


_] The filename parameter is the name of your input file. 


Disconnect Pin Simulator Only 


pind pinname 


Pin—Disconnect 
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The PIND command disconnects an input file from an interrupt pin. The 
pinname parameter identifies the interrupt pin and must be one of the five 
interrupt pins, (INT1—INT4 or BIO). 


LJ profiling 


List Pin Simulator Only 


pinl 
Pin->List 
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The PINL command displays all of the pins — unconnected pins first, followed 
by the connected pins. For a connected pin, the simulator displays the name 
of the pin and the absolute pathname of the file in the COMMAND window. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Profile, Quick 


pq_ starting point|, update rate] 


Profile—>Quick 
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The PQ command initiates a RUN command and collects a subset of the 
available statistics on the defined areas between the starting point and the 
first-encountered stopping point. PQ is similar to PF, except that PQ doesn’t 
collect exclusive or exclusive max data. 


The update rate parameter is the same as for the PF command. 


Resume Profiling Session 


pr [clear data [, update rate] | 


Profile>Resume 
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The PR command resumes the last profiling session (initiated by PF or PQ), 
starting from the current program counter. 


The optional clear data parameter tells the debugger whether or not it should 
clear out the previously collected data. The clear dataparameter can have one 
of these values: 


Value Description 

0 This is the default. The profiler will continue to collect data, adding it to 
the existing data for the profiled areas, and to use the previous internal 
profile stacks. 

nonzero’ All previously collected profile data and internal profile stacks are 


cleared. 


The update rate parameter is the same as for the PF and PQ commands. 


Change Command-Line Prompt 


prompt new prompt 


Color—Prompt 
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The PROMPT command changes the command-line prompt. The new prompt 
can be any string of characters (note that a semicolon or comma ends the 
string). 
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Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Run Code in Parallel! 


prun [-r] [-g {group | processor name}] 


none 
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The PRUN command is the basic command for running an entire program. You 
enter the command from the PDM command line to begin execution at the 
same real time for an individual processor or a group of processors. The —g 
option identifies the group or processor that the command should be sent to. 
If you don’t use this option, then code will run on the default group (dgroup). 
You can use the PHALT command to stop a global run. 


The —r (return) option for the PRUN command determines when control re- 
turns to the PDM command line: 


(_] Without -—r, control is not returned to the command line until each debug- 
ger in the group finishes running code. If you want to to break out of a syn- 
chronous command and regain control of the PDM command line, press 
in the PDM window. This will return control to the PDM com- 
mand line. However, no debugger executing the command will be inter- 
rupted. 


(_} With -r, control is returned to the command line immediately, even if a de- 
bugger is still executing acommand. You can type new commands, but the 
processors can’t execute the commands until they finish with the current 
command; however, you can perform PHALT, PESC, and STAT com- 
mands when the processors are still executing. 


Run Free in Parallel 


prunf [-g {group | processor name} 


none 
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The PRUNF command starts the processors running free, which means they 
are disconnected from the emulator. RUNF synchronizes the debuggers to 
cause the processors to begin execution at the same real time. The —g option 
identifies the group or processor that the command should be sent to. If you 
don’t use this option, then code will run on the default group (dgroup). 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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The PHALT command stops a PRUNF; note that the debugger automatically 
executes a PHALT when the debugger is invoked. 


Single-Step in Parallel 


pstep [-g {group | processor name}| [count] 


none 
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The PSTEP command single-steps synchronously through assembly lan- 
guage code with interrupts disabled. RUNF synchronizes the debuggers to 
cause the processors to begin execution at the same real time. The —g option 
identifies the group or processor that the command should be sent to. If you 
don’t use this option, then code will run on the default group (dgroup). You can 
use the PHALT command to stop a global run. 


You can use the countparameter to specify the number of statements that you 
want to single-step. 


ae | 


Note: 


If the current statement that a processor is pointing to has a breakpoint, that 
processor will not step synchronously with the other processors when you 


use the PSTEP command. However, that processor will still single-step. 
ss) 


Exit Debugger 


quit 
none 
basic debugger PDM profiling 
The QUIT command exits the debugger and returns to the operating system. 


If you enter this command from the PDM, the PDM and all debuggers running 
under the PDM are exited. 
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reload 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Reload Object Code 


reload [object filename] 


Load—Reload 
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The RELOAD command loads only an object file without loading its asso- 
ciated symbol table. This is useful for reloading a program when target 
memory has been corrupted. If you enter the RELOAD command without 
specifying a filename, the debugger reloads the file that you loaded last. 


Reset Target System 


reset 


Load—ReseT 


basic debugger LJ PDM profiling 


The RESET command resets the target system (emulator only), simulator, or 
EVM and reloads the monitor. Note that this is a software reset. 


If you are using the simulator and execute the RESET commana, the simulator 
simulates the 'C5x processor and peripheral reset operation, putting the pro- 
cessor in a known state. 


Reset PC to Program Entry Point 
restart 
rest 


Load—REstart 
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The RESTART or REST command resets the program to its entry point. (This 
assumes that you have already used one of the load commands to load a 
program into memory.) 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Return to Function’s Caller 
return 
ret 


none 
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The RETURN or RET command executes the code in the current C function 
and halts when execution reaches the caller. Breakpoints do not affect this 
command, but you can halt execution by pressing the left mouse button or 
pressing (Sc). 


Run Code 


run [expression] 


Run=F5 
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The RUN command is the basic command for running an entire program. The 
command's behavior depends on the type of parameter you supply: 


[__] If you don’t supply an expression, the program executes until it encounters 
a breakpoint or until you press the left mouse button or press (sc) . 


_] If you supply a logical or relational expression, the run becomes 
conditional (described in detail on page 7-17). 


[_] If you supply any other type of expression, the debugger treats the expres- 
sion as a count parameter. The debugger executes count instructions, 
halts, and updates the display. 
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Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Benchmark Code 


runb 


none 
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The RUNB command executes a specific section of code and counts the 
number of CPU clock cycles consumed by the execution. In order to operate 
correctly, execution must be halted by a software breakpoint. After RUNB ex- 
ecution halts, the debugger stores the number of cycles into the CLK pseudo- 
register. For a complete explanation of the RUNB command and the bench- 
marking process, read Section 7.7, Benchmarking, on page 7-19. 
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Run Free EVM & Emulator Only 


runf 


none 
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The RUNF command disconnects the emulator or EVM from the target system 
while code is executing. When you enter RUNF, the debugger clears all break- 
points, disconnects the emulator or EVM from the target system, and causes 
the processor to begin execution at the current PC. You can quit the debugger, 
or you can continue to enter commands. However, any command that causes 
the debugger to access the target at this time produces an error. 
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The HALT command stops a RUNF; note that the debugger automatically 
executes a HALT when the debugger is invoked. 


Add Stopping Point 


sa address 


Stop-points—Add 
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The SA command adds a stopping point at address. The address can be a 
label, a function name, or a memory address. 


Syntax 


Menu selection 


Environments 


Description 
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Change Screen Colors 


scolor area name, attribute; |, attributes |, attribute3 |, attribute,] ] | 


Color—Config 
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The SCOLOR command changes the color of specified areas of the debugger 
display and updates the display immediately. The area name parameter identi- 
fies the area of the display that is affected. The attributes identify how the area 
is affected. The first two attribute parameters usually specify the foreground 
and background colors for the area. If you do not supply a background color, 
the debugger uses black as the background. 


Valid values for the attribute parameters include: 


black blue green cyan 
red magenta yellow white 
bright blink 


Valid values for the area name parameters include: 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify the attribute. If you supply ambiguous aftrib- 
utenames, the debugger interprets the names in this order: black, blue, bright, 
blink. If you supply ambiguous area names, the debugger interprets them in 
the order that they’re listed above (left to right, top to bottom). 
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Syntax 
Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Syntax 
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Environments 


Description 
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Load Screen Configuration 


sconfig [filename] 


Color—Load 
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The SCONFIG command restores the display to a specified configuration. 
This restores the screen colors, window positions, window sizes, and border 
styles that were saved with the SSAVE command into filename. If you don’t 
supply a filename, the debugger looks for init.clr. The debugger searches for 
the specified file in the current directory and then in directories named with the 
D_DIR environment variable. 


Delete Stopping Point 


sd address 


Stop-points—Delete 
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The SD command deletes the stopping point at address. 

Send Debugger Command to Individual Debuggers 

send [-r] [-g {group| processor name}| debugger command 

none 
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The SEND command sends any debugger command to an individual proces- 
sor or to a group of processors. If the command produces a message, it will 
be displayed in the COMMAND window for the appropriate debugger(s) and 
also in the PDM window. 


[_} The -g option specifies the group or processor that the debugger com- 
mand should be sent to. If you don’t use this option, the command is sent 
to the default group (dgroup). 


(_] The -t (return) option determines when control returns to the PDM com- 
mand line: 


HM Without -t, control is not returned to the command line until each de- 
bugger in the group finishes running code. Any results that are printed 
in the COMMAND window of the individual debuggers will also be 
echoed in the PDM command window. These results will be displayed 
by processor. 


Syntax 


Menu selection 


Environments 


Description 
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If you want to break out of asynchronous command and regain control 
ofthe PDMcommandline, press inthe PDM window. This 
will return control to the PDM command line. However, no debugger 
executing the command will be interrupted. 


H@ With-tr, control is returned to the command line immediately, even if a 
debugger is still executing a command. When you use -r, you do not 
see the results of the commands that the debuggers are executing. 


Set a Variable to a String 


set [group name [= list of processor names]] 
set [variable [= string value]] 


none 


L] basic debugger PDM te! profiling 


The SET command allows you to create groups of processors to which you can 
send commands. With the SET command you can: 


[_} Define a group of processors. It is useful to define a group when you 
plan to send commands to the same set of processors. The commands 
are sent to the processors in the same order in which you added the pro- 
cessors to the group. To define a group, specify a group name and then 
list the processors you want in the group. 


[_] Set the default group. Defining a default group provides you with a short- 
hand method of maintaining members in a group or of sending commands 
to the same group. To set up the default group, use the SET command with 
a special group name called dgroup. 


_} Modify an existing group or creating a group based on another 
group. Once you've created a group, you can add processors to it by us- 
ing the SET command and preceding the existing group namewith a dollar 
sign ($) in the list of processors. Youcan also use a group as part of anoth- 
er group by preceding the existing group’s name with a dollar sign. The 
dollar sign tells the PDM to use the processors listed previously in the 
group as part of the new list of processors. 


(_] List all groups of processors. You can use the SET command without 
any parameters to list all the processors that belong to a group, in the order 
in which they were added to the group. 


You can also use the SET command with system-defined variables to: 
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Syntax 


Menu selection 


Environments 


Description 
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[_] Change the prompt for the PDM. To change the PDM prompt, use the 
SET command with the system variable called prompt. For example, to 
change the PDM prompt to 3PROCs, enter: 
set prompt = 3PROCs 

(_] Check the execution status of the processors. In addition to displaying 
the execution status of a processor or group of processors, the STAT com- 
mand (described on page 13-56) sets a system variable called status. If 
allof the processors in the specified group are running, the status variable 
is setto 1. If one or more of the processors in the group is halted, the status 
variable is set to 0. 

You can use this variable when you want an instruction loop to execute un- 
til a processor halts (the LOOP/ENDLOOP command is described on 
page 13-31): 

(_] Create your own system variables. You can use the SET command to 

create your own system variables that you can use with PDM commands. 


For more information about creating your own system variables, see page 
2-18. 


Set Default Data-Display Format 


setf [data type, display format | 


none 
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The SETF command changes the display format for a specific data type. If you 
enter SETF with no parameters, the debugger lists the current display format 
for each data type. 


[_] The data type parameter can be any of the following C data types: 


char short uint ulong double 
uchar int long float ptr 


(_] The display format parameter can be any of the following characters: 


Parameter Result Parameter Result 


. Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


Syntax 
Menu selection 
Environments 


Description 


Alphabetical Summary of Debugger and PDM Commands setf, size 


Only a subset of the display formats can be used for each data type. Listed 
below are the valid combinations of data types and display formats. 


Data Valid Display Formats Data Valid Display Formats 
Type c do x e f p s u/]|Type cdoxefpsu 
char (c) Vv v4 V | long (d) Vyvyv 4 V 
uchar(d) V Vv Vv Vv V]ulong(d) Vv v Vv V 
short(d) Vv v v \ | float (e) Vvv 

int (d) Vv vv V | double (e) Vv Vv 

uint (d) Vv v4 V | ptr (p) Vv Vv 


To return all data types to their default display format, enter: 


setf * 


Size Active Window 


size [wiath, length | 


none 
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The SIZE command changes the size of the active window. You can use the 
SIZE command in one of two ways: 


| By supplying a specific width and length or 
[__] By omitting the width and /ength parameters and using function keys to in- 
teractively resize the window. 


Valid values for the width and length depend on the screen size and the win- 
dow position on the screen. If the window is in the upper left corner of the 
screen, the maximum size of the window is the same as the screen size minus 
one line. (The extra line is needed for the menu bar.) For example, if the screen 
size is 80 characters by 25 lines, the largest window size is 80 characters by 
24 lines. 


If a window is in the middle of the display, you can’t size it to the maximum 
height and width—you can size it only to the right and bottom screen borders. 
The easiest way to make a window as large as possible is to zoom it, as 
described on page 4-23. 
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Syntax 
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Environments 
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If you enter the SIZE command without width and length parameters, you can 
use arrow keys to size the window. 


Makes the active window one line longer. 

Makes the active window one line shorter. 

Makes the active window one character narrower. 
Makes the active window one character wider. 


UOEBE 


When you're finished using the arrow keys, you must press or [#]. 


List Stopping Point 


sl 


Stop-points—List 
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The SL command lists all of the currently set stopping points. 

Load Symbol Table 

sload object filename 

Load—Symbols 
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The SLOAD command loads the symbol table of the specified object file. 
SLOAD is useful in a debugging environment in which the debugger cannot, 
or need not, load the object code (for example, if the code is in ROM). SLOAD 
clears the existing symbol table before loading the new one but does not 
modify memory or set the program entry point. Note that SLOAD closes the 
WATCH and DISP windows. 


Enable Error Beeping 


sound {on | off} 


none 
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You can cause a beep to sound every time a debugger error message is 
displayed. This is useful if the COMMAND window is hidden (because you 
wouldn't see the error message). By default, sound is off. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


ssave 


Syntax 
Menu selection 


Environments 


Description 
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Invoke the ’C5x Debugger 


spawn emud5x -nprocessorname_ [invocation options] 


none 
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You must invoke a debugger for each processor that you want the PDM to con- 
trol. To invoke a debugger, use the SPAWN command. 


(_] emubdx is the executable that invokes the debugger. The PDM associates 
the processor name with the actual processor according to which execut- 
able you use. In order to invoke a debugger, the PDM must be able to find 
the executable file for that debugger. The PDM will first search the current 
directory and then search the directories listed with the PATH statement. 


[_] —-n processor name supplies a processor name. You mustuse the —n op- 
tion since the PDM uses processor names to identify the various debug- 
gers that are running. The processor name can consist of up to eight al- 
phanumeric or underscore characters and must begin with an alphabetic 
character. Note that the name is not case sensitive. The processor name 
must match one of the names defined in your board configuration file (see 
Appendix C). 


Reset Stopping Point 


sr 


Stop-points—Reset 
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The SR command resets (deletes) a// currently set stopping points. 
Save Screen Configuration 


ssave [filename] 


Color—Save 
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The SSAVE command saves the current screen configuration to a file. This 
saves the screen colors, window positions, window sizes, and border styles. 
The filename parameter names the new screen configuration file. You can 
include path information (including relative pathnames); if you don’t supply 
path information, the debugger places the file in the current directory. If you 
don’t supply a filename, then the debugger saves the current configuration into 
a file named init.clr and places the file in the current directory. 
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Syntax 
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Environments 


Description 
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Find the Execution Status of Processors 


stat [{-g group | processor name}] 


none 
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The STAT command tells you whether a processor is running or halted. If a pro- 
cessor is halted when you execute this command, then the PDM also lists the 
current PC value for that processor. If you don’t use the -g option, the PDM 
displays the status of the processors in the default group (dgroup). 


Single-Step 


step [expression] 


Step=F8 (in disassembly) 
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The STEP command single-steps through assembly language or C code. If 
you're in C code, the debugger executes one C statement at atime. In assem- 
bly or mixed mode, the debugger executes one assembly language statement 
at a time. 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug op- 
tion). When function execution completes, single-step execution returns to the 
caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 


The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional 
single-step execution (Running code conditionally, page 7-17, discusses this 
in detail). 


Syntax 


Menu selection 


Environments 


Description 
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Enter Operating-System Command 


Basic debugger: system [DOS command |, flag] | 

PDM: system operating-system command 

none 
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You can use the SYSTEM command to enter operating-system commands: 


[_] The debugger version of the SYSTEM command allows you to enter DOS 


commands without explicitly exiting the debugger environment. 


If you enter SYSTEM with no parameters, the debugger will open asystem 
shell and display the operating-system prompt. At this point, you can enter 
any DOS command. (In MS-DOS, available memory may limit the com- 
mands that you can enter.) When you finish, enter: 


exit 


If you prefer, you can supply the DOS command as a parameter to the 
SYSTEM command. If the result of the command is a message or other 
display, the debugger will blank the top of the debugger display to show the 
information. In this case, you can use the flag parameter to tell the debug- 
ger whether or not it should hesitate after displaying the information. Flag 
may be aOoral. 


0 If you supply a value of 0 for flag, the debugger immediately re- 
turns to the debugger environment after the last item of informa- 
tion is displayed. 


1 If you supply a value of 1 for flag, the debugger does not return to 
the debugger environment until you press @). (This is the default.) 


The PDM version of the SYSTEM command allows you to enter a single 
operating-system command without explicitly exiting the PDM environ- 
ment. You cannot enter more than one operating-system command with 
the PDM version of the SYSTEM command. 
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Syntax 
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Environments 


Description 


Syntax 


Menu selection 
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Execute Batch File 


Basic debugger: take batch filename [, suppress echo flag] 
PDM: take batch filename 

none 
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The TAKE command tells the debugger or the PDM to read and execute com- 
mands from a batch file. The batch filename parameter identifies the file that 
contains commands. If you don’t supply a pathname as part of the filename, 
the PDM first looks in the current directory and then searches directories 
named with the D_ DIR environment variable. 


The batch filename for the PDM version of this command must have a .pdm 
extension, or the PDM will not be able to read the file. In addition, the batch 
file that the PDM reads can contain only PDM commands. 


By default, the debugger echoes the commands to the output area of the 
COMMAND window and updates the display as it reads the commands from 
the batch file. For the debugger, you can change this behavior: 


__] Ifyou don’tuse the suppress echo flag parameter, or if you use it but supply 
a nonzero value, then the debugger behaves in the default manner. 


[_] If you would like to suppress the echoing and updating, use the value 0 for 
the suppress echo flag parameter. 


Delete Alias Definition 


unalias alias name 
unalias * 


none 
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The UNALIAS command deletes defined aliases. 

_] Todelete a single alias, enter the UNALIAS command with an alias name. 
For example, to delete an alias named NEWMAP, enter: 
unalias NEWMAP 

[(_] To delete all aliases, enter an asterisk instead of an alias name: 
unalias * 


Note that the * symbol does not work as a wildcard. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


vaa 


Syntax 
Menu selection 


Environments 


Description 
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Delete Group 
unset group name 
unset * 


none 
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The UNSET command deletes a group of processors. You can use this com- 
mand in conjunction with the SET command to remove a particular processor 
from a group. 


To delete all groups, enter an asterisk instead of a group name: 
unset * 
Note that the * symbol does not work as a wildcard. 


Note: 


When you use UNSET * to delete all of your system variables and processor 
groups, variables such as prompt, status, and dgroup are also deleted. 


Use New Directory 


use [directory name] 


none 
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The USE command allows you to name an additional directory that the debug- 
ger can search when looking for source files. You can specify only one direc- 
tory ata time. 


If you enter the USE command without specifying a directory name, the debug- 
ger lists all of the current directories. 


Save All Profile Data to a File 


vaa_ filename 


View—>Save—-All views 
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The VAA command saves all statistics collected during the current profiling 
session. The data is stored in a system file. 
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vac, version, vr 


vac 
Syntax 
Menu selection 


Environments 


Description 


version 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger and PDM Commands 


Save Displayed Profile Data to a File 


vac filename 


View—Save->Current view 
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The VAC command saves all statistics currently displayed in the PROFILE 
window. (Statistics that aren’t displayed aren’t saved.) The data is stored ina 
system file. 


LJ basic debugger 


Display the Current Debugger Version 


version 


none 
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The VERSION command displays the debugger’s copyright date and the cur- 
rent version number of the debugger, silicon, XDS, etc. 


Reset PROFILE Window Display 


vr 


View—Reset 


LJ ppm profiling 


The VR command resets the display in the PROFILE window so that all 
marked areas are listed and statistics are displayed with default labels and in 
the default sort order. 
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Syntax 
Menu selection 


Environments 


Description 
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Add Item to WATCH Window 


wa expression [,| label] [, display formal] 


Watch—Add 
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The WA command displays the value of expression in the WATCH window. If 
the WATCH window isn’t open, executing WA opens the WATCH window. The 
expression parameter can be any C expression, including an expression that 
has side effects. If the expression identifies an address, you can follow it with 
@prog to identify program memory or with @data to identify data memory. If 
you are using an emulator or EVM, or you can follow an address with @io to 
identify I/O space. Without the suffix, the debugger treats an address expres- 
sion as a program-memory location. 


WA is most useful for watching an expression whose value changes over time; 
constant expressions serve no useful function in the watch window. The /abel 
parameter is optional. When used, it provides a label for the watched entry. If 
you don't use a /abel, the debugger displays the expression in the label field. 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


7 Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


If you want to use a display format parameter without a /abe/ parameter, just 
insert an extra comma. For example: 


wa PC,,d 
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wd, whatis, win Alphabetical Summary of Debugger and PDM Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Delete Item From WATCH Window 


wd index number 


Watch—Delete 
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The WD command deletes a specific item from the WATCH window. The WD 
command's index number parameter must correspond to one of the watch 
indexes listed in the WATCH window. 


Find Data Type 


whatis symbol 


none 
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The WHATIS command shows the data type of symbol in the COMMAND 
window display area. The symbol can be any variable (local, global, or static), 
a function name, structure tag, typedef name, or enumeration constant. 


Select Active Window 


win WINDOW NAME 


none 
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The WIN command allows you to select the active window by name. Note that 
the WINDOW NAME is in uppercase (matching the name exactly as 
displayed). You can spell out the entire window name, but you really need to 
specify only enough letters to identify the window. 


If several windows of the same type are visible on the screen, don’t use the 
WIN command to select one of them. If you supply an ambiguous name (such 
as C, which could stand for CPU or CALLS), the debugger selects the first 
window it finds whose name matches the name you supplied. If the debugger 
doesn’t find the window you asked for (because you closed the window or 
misspelled the name), then the WIN command has no effect. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 
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Reset WATCH Window 


wr 
Watch—Reset 
basic debugger L] PDM LJ profiling 


The WR command deletes all items from the WATCH window and closes the 
window. 


Zoom Active Window 


zoom 


none 


basic debugger LJ PDM profiling 


The ZOOM command makes the active window as large as possible. To 
“unzoom’” a window, enter the ZOOM command a second time; this returns the 
window to its prezoom size and position. 
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13.4 Summary of Profiling Commands 


The following tables summarize the profiling commands that are used for 
marking, enabling, disabling, and unmarking areas and for changing the 
display in the PROFILE window. These commands are easiest to use from the 
pulldown menus, so they are not included in the alphabetical command 
summary. The syntaxes for these commands are provided here so that you 
can include them in batch files. 


Table 13—1.Marking Areas 


To mark this area 


Lines 
[] By line number, address 
(} All lines in a function 


Ranges 
(J By line numbers 


Functions 

_} By function name 

(] All functions in a module 
(] All functions everywhere 


C only 


MCLE 
MCLF 


MCRE 


MCFE 
MCFM 
MCFG 


filename, line number 
function 


filename, line number, line number 


function 
filename 


Table 13-2. Disabling Marked Areas 


To disable this area 


Lines 

_} By line number, address 
(] All lines in a function 

_} All lines in a module 

_} All lines everywhere 


Ranges 


All ranges in a function 
All ranges in a module 
All ranges everywhere 


Functions 

_] By function name 

(] All functions in a module 
_] All functions everywhere 


All areas 

(] All areas in a function 
(j All areas in a module 
(] All areas everywhere 
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By line numbers, addresses 


C only 


DCLE 
DCLF 
DCLM 
DCLG 


DCRE 
DCRF 
DCRM 
DCRG 


DCFE 
DCFM 
DCFG 


DCAF 
DCAM 
DCAG 


filename, line number 
function 
filename 


filename, line number 
function 
filename 


function 
filename 


function 
filename 


Disassembly only 


MALE address 
MALF function 


MARE. address, address 


not applicable 


Disassembly only C and disassembly 


DALE 
DALF 
DALM 
DALG 


address 
function 
filename 


DARE 
DARF 
DARM 
DARG 


address 
function 
filename 


not applicable 


DAAF function 
DAAM filename 
DAAG 


not applicable 
DBLF function 
DBLM filename 
DBLG 


not applicable 
DBRF function 
DBRM filename 
DBRG 


not applicable 
DBFM filename 
DBFG 


DBAF function 
DBAM filename 
DBAG 


Table 13-—3.Enabling Disabled Areas 
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To enable this area C only Disassembly only C and disassembly 
Lines 

(] By line number, address ECLE filename, linenumber EALE address not applicable 

[] All lines in a function ECLF function EALF function EBLF function 
(} All lines in a module ECLM filename EALM filename EBLM filename 
_] All lines everywhere ECLG EALG EBLG 

Ranges 

[} By line numbers, addresses ECRE filename, line number ARE address not applicable 

[J All ranges in a function ECRF function EARF function EBRF function 
(] All ranges in a module ECRM filename EARM filename EBRM filename 
_] All ranges everywhere ECRG EARG EBRG 
Functions 

(_} By function name ECFE function not applicable not applicable 

[(_] All functions in a module ECFM filename EBFM filename 
_] All functions everywhere ECFG EBFG 

All areas 

(] All areas in a function ECAF function EAAF function EBAF function 
(] All areas in a module ECAM filename EAAM filename EBAM filename 
(] All areas everywhere ECAG EAAG EBAG 
Table 13-4. Unmarking Areas 

To unmark this area C only Disassembly only C anddisassembly 
Lines 

[] By line number, address UCLE filename, linenumber UALE address not applicable 

[J All lines in a function UCLF function UALF function UBLF function 
_] All lines in a module UCLM filename UALM filename UBLM filename 
[J] All lines everywhere UCLG UALG UBLG 

Ranges 

(_} By line numbers, addresses] UCRE filename, line number UARE address not applicable 

[J All ranges in a function UCRF function UARF function UBRF function 
(] All ranges in a module UCRM filename UARM filename UBRM filename 
(Jj All ranges everywhere UCRG UARG UBRG 
Functions 

(_} By function name UCFE function not applicable not applicable 

[] All functions in a module UCFM filename UBFM filename 
_] All functions everywhere UCFG UBFG 

All areas 

(] All areas in a function UCAF function UAAF function UBAF function 
_] All areas in a module UCAM filename UAAM filename UBAM filename 
[Jj All areas everywhere UCAG UAAG UBAG 
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Table 13-5. Changing the PROFILE Window Display 


(a) Viewing specific areas 


To view this area C only Disassembly only C and disassembly 
Lines 
(J Byline number, address VFCLE filename, linenumber \WFALE address not applicable 
(} All lines in a function VFCLF function VFALF function VFBLF function 
_} All lines in a module VFCLM filename VFALM filename VFBLM filename 
_j All lines everywhere VFCLG VFALG VFBLG 
Ranges 
[} By line numbers, addresses VFCRE filename, line number VFARE address not applicable 
(] All ranges in a function VFCRF function VFARF function VFBRF_ function 
(] All ranges in a module VFCRM filename VFARM filename VFBRM_ filename 
_j All ranges everywhere VFCRG VFARG VFBRG 
Functions 
(_} By function name VFCFE function not applicable not applicable 
[} All functions ina module VFCFM filename VFBFM filename 
_] All functions everywhere VFCFG VFBFG 
All areas 
(] All areas in a function VFCAF function VFAAF function VFBAF function 
(] All areas in a module VFCAM filename VFAAM filename VFBAM_ filename 
(] All areas everywhere VFCAG VFAAG VFBAG 
(b) Viewing different data (c) Sorting the data 
To view this information Use this To sort on this data Use this 
command command 
Count VDC Count vsc 
Inclusive VDI Inclusive vsi 
Inclusive, maximum VDN Inclusive, maximum VSN 
Exclusive VDE Exclusive VSE 
Exclusive, maximum VDX Exclusive, maximum VSX 
Address VDA Address VSA 
All VDL Data VSD 
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13.5 Summary of Special Keys 


The debugger provides function key, cursor key, and command key se- 


quences for performing a variety of actions: 


Editing text on the command line 
Using the command history 

Switching modes 

Halting or escaping from an action 
Displaying the pulldown menus 
Running code 

Selecting or closing a window 

Moving or sizing a window 

Scrolling through a window's contents 
Editing data or selecting the active field 


DUUUUOUUOUOU 


Editing text on the command line 


To do this 


Enter the current command (note that if you press the return key 
in the middle of text, the debugger truncates the input text at the 
point where you press this key) 


Use these 
function keys 


Using the command history 


Move back over text without erasing characters (CONTROL ) 
(ERE) 
Move forward through text without erasing characters (CONTROL ) 
Move back over text while erasing characters (DELETE ) 
Move forward through text while erasing characters (SPACE ) 
Insert text into the characters that are already on the command CINSERT ) 
line 
Use these 
To do this function keys 
Repeat the last command that you entered 
Move backward, one command at a time, through the command 
history 
Move forward, one command at a time, through the command 


history 
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Switching modes 


Use this 
To do this function key 


Switch debugging modes in this order: 


co ———» assembly ———__» mas 


Halting or escaping from an action 


The escape key acts as an end or undo key in several situations. 


Use this 
To do this function key 
[(_} Halt program execution ESC 
[J Close a pulldown menu 
[_} Undo an edit of the active field in a data-display window 
(pressing this key leaves the field unchanged) 
[(_} Halt the display of a long list of data in the display area of 
the COMMAND window 
Displaying pulldown menus 
Use these 
To do this function keys 
Display the Load menu (ALT) (ED 
Display the Break menu (ALT) (B) 
Display the Watch menu (ALT) W) 
Display the Memory menu (ALT) (M) 
Display the Color menu ALT) (C) 
Display the MoDe menu ALT) (D) 
Display the Pin menu AN ©) 
Display the Analysis menu (ALT) (A) 
(©) or 


Display an adjacent menu 

Execute any of the choices from a displayed pulldown menu Press the high- 
lighted letter 
corresponding 
to your choice 
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Running code 


Use these 
To do this function keys 


Run code from the current PC (equivalent to the RUN command 
without an expression parameter) 


Single-step code from the current PC (equivalent to the STEP 
command without an expression parameter) 


Single-step code from the current PC; step over function calls F10 
(equivalent to the NEXT command without an expression 
parameter) 


Selecting or closing a window 


Use these 
To do this function keys 


Select the active window (pressing this key makes each window 
active in turn; stop pressing the key when the desired window 
becomes active) 


Close the CALLS, WATCH, DISP, or additional MEMORY window 
(the window must be active before you can close it) 


Moving or sizing a window 


You can use the arrow keys to interactively move a window after entering the 
MOVE or SIZE command without parameters. 


Use these 
To do this function keys 
(} Move the window down one line ) 
(J Make the window one line longer 
__} Move the window up one line (T) 
(} Make the window one line shorter 
(} Move the window left one character position ©) 
(} Make the window one character narrower 
(} Move the window right one character position GC) 
[] Make the window one character wider 
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Scrolling a window’s contents 


These descriptions and instructions for scrolling apply to the active window. 
Some of these descriptions refer to specific windows; if no specific window is 
named, then the description/instructions refer to any window that is active. 


Use these 

To do this function keys 
Scroll up through the window contents, one window length at (PAGE UP } 
a time 
Scroll down through the window contents, one window length (PAGE DOWN) 
at atime 
Move the field cursor up, one line at a time Mm 
Move the field cursor down, one line at a time W) 
_] FILE window only: Scroll left 8 characters at a time (<) 
[| Other windows: Move the field cursor left one field; at the first 

field on a line, wrap back to the last fully displayed field on 

the previous line 
(J FILE window only: Scroll right 8 characters at a time 
[J Other windows: Move the field cursor right one field; at the last 


field on a line, wrap around to the first field on the next line 


FILE window only: Adjust the window's contents so that the first 
line of the text file is at the top of the window 


FILE window only: Adjust the window's contents so that the last 
line of the text file is at the bottom of the window 


DISP windows only: Scroll up through an array of structures 


DISP windows only: Scroll down through an array of structures 


CONTROL 
PAGE UP 


(CONTROL } 


PAGE DOWN 


Editing data or selecting the active field 
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The F9 function key makes the current field (the field that the cursor is pointing 
to) active. This has various effects, depending on the field. 


Use these 


To do this f 


CALLS window: Display the source to a listed function 
Any data-display window: Edit the contents of the current field 


DISP window: Open an additional DISP window to display a 
member that is an array, structure, or pointer 


COCO 


unction keys 


FILE or DISASSEMBLY window: Set or clear a breakpoint 
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Basic Information 
About C Expressions 


Many of the debugger commands take C expressions as parameters. This al- 
lows the debugger to have a relatively small, yet powerful, instruction set. Be- 
cause C expressions can have side effects—that is, the evaluation of some 
types of expressions can affect existing values—you can use the same com- 
mand to display or to change a value. This reduces the number of commands 
in the command set. 


This chapter contains basic information that you'll need to know in order to use 
C expressions as debugger command parameters. 


Topic Page 
14.1 C Expressions for Assembly Language Programmers 14-2 
14.2 Using Expression Analysis in the Debugger 14-4 

Restrictions 14-4 
Additional features 14-4 
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14.1 C Expressions for Assembly Language Programmers 
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It’s not necessary for you to be an experienced C programmer in order to use 
the debugger. However, in order to use the debugger’s full capabilities, you 
should be familiar with the rules governing C expressions. You should obtain 
a copy of The C Programming Language (first or second edition) by Brian 
W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood 
Cliffs, New Jersey. This book is referred to in the C community, and in Texas 
Instruments documentation, as K&R. 


nn sss sae ns sn ess Sas | 
Note: 


A single value or symbol is a legal C expression. 
| ee 


K&R contains a complete description of C expressions; to get you started, 
here’s asummary of the operators that you can use in expression parameters. 


() Reference operators 


—> indirect structure reference : direct structure reference 
[] array reference _ indirection (unary) 
& address (unary) 


(_] Arithmetic operators 


+ addition (binary) — subtraction (binary) 
* multiplication / division 
% modulo — negation (unary) 


(type) typecast 


(_] Relational and logical operators 


> greater than >= greater than or equal to 
< less than <= less than or equal to 
== is equal to l= is not equal to 

&& logical AND || logical OR 


| logical NOT (unary) 
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(J Increment and decrement operators 


++ increment —— decrement 


These unary operators can precede or follow a symbol. When the operator 
precedes a symbol, the symbol value is incremented/decremented before 
itis used in the expression; when the operator follows a symbol, the sym- 
bol value is incremented/decremented after it is used in the expression. 
Because these operators affect the symbol’s final value, they have side 
effects. 


[) Bitwise operators 


& bitwise AND | bitwise OR 
as bitwise exclusive-OR << __ left shift 
>> right shift ~ 1s complement (unary) 


(J Assignment operators 


= assignment += assignment with addition 

= assignment with subtraction /= assignment with division 

%= assignment with modulo &= assignmentwith bitwise AND 
N= assignment with bitwise XOR |= assignment with bitwise OR 
<<= assignment with left shift >>= assignment with right shift 


7 assignment with multiplication 
These operators support a shorthand version of the familiar binary expres- 


sions; for example, X = X + Y canbe written in C as X += Y. Because these 
operators affect a symbol’s final value, they have side effects. 


Basic Information About C Expressions 14-3 


Using Expression Analysis in the Debugger 


14.2 Using Expression Analysis in the Debugger 


Restrictions 


Additional features 
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The debugger’s expression analysis is based on C expression analysis. This 
includes all mathematical, relational, pointer, and assignment operators. 
However, a few limitations, as well as a few additional features, are not 
described in K&R C. 


The following restrictions apply to the debugger’s expression analysis 
features. 


LL} 
L} 


The sizeof operator is not supported. 


The comma operator (,) is not supported (commas are used to separate 
parameter values for the debugger commands). 


Function calls and string constants are currently not supported in expres- 
sions. 


The debugger supports a limited capability of type casts; the following 
forms are allowed: 


( basic type ) 

( basic type * ...) 

( [ structure/union/enum] _structure/union/enum tag ) 

( [ structure/union/enum] structure/union/enum tag* ... ) 


Note that you can use up to six *s in a cast. 


All floating-point operations are performed in double precision using stan- 
dard widening. (This is transparent.) Floats are represented in IEEE floa- 
ting-point format. 


All registers can be referenced by name. The TMS320C5x’s auxiliary reg- 
isters are treated as integers and/or pointers. 


Void expressions are legal (treated like integers). 


The specification of variables and functions can be qualified with context 
information. Local variables (including local statics) can be referenced 
with the expression form: 


function name.local name 
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This expression format is useful for examining the automatic variables ofa 
function that is not currently being executed. Unless the variable is static, 
however, the function must be somewhere in the current call stack. Note 
that if you wantto see local variables from the currently executing function, 
you need not use this form; you can simply specify the variable name (just 
as in your C source). 


File-scoped variables (such as statics or functions) can be referenced with 
the following expression form: 


filename.function name 
or filename.variable name 


This expression format is useful for accessing a file-scoped static variable 
(or function) that may share its name with variables in other files. 


Note that in this expression, filename does not include the file extension; 
the debugger searches the object symbol table for any source filename 
that matches the input name, disregarding any extension. Thus, if the vari- 
able ABC is in file source.c, you can specify it as source.ABC. 


Note that these expression forms can be combined into an expression of 
the form: 


filename.function name.variable name 


Any integral or void expression can be treated as a pointer and used with 
the indirection operator (*). Here are several examples of valid use of a 
pointer in an expression: 

*123 

*AR5 

*(AR2 + 123) 

*(I*J) 

By default, the values are treated as integers (that is, these expressions 
point to integer values). 


Any expression can be typecast to a pointer to a specific type (overriding 
the default of pointing to an integer, as described above). 

Hint: You can use casting with the WA and DISP commands to display 
data in a desired format. 

For example, the expression: 

*(float *)10 

treats 10 as apointer to a floating-point value at location 10 in memory. In 
this case, the debugger fetches the contents of memory location 10 and 
treats the contents as a floating-point value. If you use this expression as a 
parameter for the DISP command, the debugger displays memory 
contents as an array of floating-point values within the DISP window, be- 
ginning with memory location 10 as array member [0]. 
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Note how the first expression differs from the expression: 

(float) *10 

In this case, the debugger fetches an integer from address 10 and con- 
verts the integer to a floating-point value. 

You can also typecast to user-defined types such as structures. For exam- 
ple, in the expression: 

((struct STR *)10)->field 


the debugger treats memory location 10 as a pointer to a structure of type 
STR (assuming that a structure is at address 10) and accesses a field from 
that structure. 
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Customizing the Analysis Interface 


The interface to the ’C5x analysis module is register-based. In most cases, the 
Analysis Count Events and Analysis Break Events dialog boxes provide a suf- 
ficient means of counting events and setting hardware breakpoints. In some 
cases, however, you may want to define more complex conditions for the pro- 
cessor to detect. Or, you may want to write a batch file that defines counting 
or breakpoint conditions. In either case, you can accomplish these tasks by 
accessing the analysis registers through the debugger. This appendix ex- 
plains how to access these registers. 


Topic Page 
A.1.| Summary of Aliased Commands A-2 
Enabling the analysis interface A-4 
Enabling the EMU0/1 pins A-4 
Enabling event counting A-5 
Setting breakpoints on a single program or data address A-6 
Breaking on event occurrences A-7 
Qualifying on a read or write A-8 
Resetting the analysis interface A-9 
A.2_ Using the Analysis Registers A-9 
anaenbl (Enable Analysis) A-10 
anastat (Analysis Status) A-10 
datbrkp (Data Breakpoint Address) A-11 
datqual (Data Breakpoint Qualifier) A-11 
evicntr (Event Counter) A-11 
eviselt (Select the Event for Counting) A-12 
hbpenbl (Select Hardware Breakpoints) A-13 
pgabrkp (Program Address Breakpoint) A-13 
pgaqual (Program Breakpoint Qualifier) A-13 
ptraceO/ptrace 1/ptrace2 (Discontinuity Trace Samples 0-2) A-14 
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A.1 Summary of Aliased Commands 


A basic set of analysis commands is defined in the analysis.cmd file supplied 
in your ’C5x debugger package. These commands, like the analysis dialog 
boxes, load the analysis registers with your specified values. You must TAKE 
the analysis.cmd file before you can use any of these commands. To do this, 
enter: 


take analysis.cmd 


By default, the debugger echoes the file to the output area of the COMMAND 
window. However, you can view the entire file by using the FILE command to 
display its contents in the FILE window. Table A—1 shows the predefined com- 
mands along with their menu equivalents. 


The aliased commands, created in the analysis.cmd file, are provided to help 
you familiarize yourself with the analysis registers and how they work. The 
aliases are simply a starting point for you to build upon to create your own com- 
mands. 


Table A—1. The Analysis Commands Found in the analysis.cmd File 


Menu —> 

Command Dialog Box Description Page 

asys_emuOout Emulator pins > Set EMUO pin to output A-4 
EMUO trigger out 

asys_emutout Emulator pins > Set EMU1 pin to output A-4 
EMUO trigger out 

asys_extcnt Emulator pins > Use the external counteronthe A-4 
External clock emulator 

asys_ off Analysis > Turn off the analysis interface A-4 
Enable/Disable 

asys_on Analysis > Turn on the analysis interface A-4 
Disable/Enable 

asys_reset none Reset the analysis interface A-9 

cnt_br Count > Count any branches detected A-5 
Branch taken 

cnt_call Count > Count any calls detected A-5 
Call taken 

cnt_clock Count > Count CPU clock cycles A-5 
CPU clock 

cnt_data Count > Count any data accesses A-5 
Data bus 

cnt_ins Count > Count any instructions fetched A-5 
Instruction fetch 

ent_intr Count > Count any interrupts/traps A-5 


Interrupt/trap taken 


detected 


Command 


cnt_load value 


cnt_pclk 


cnt_prog 


cnt_ret 


data_brk_add address 


or symbol name 


data_qual_r 


data_qual_rw 


data_qual_w 


prog_brk_add aa- 
dress or function 
name 


prog_qual_iaq 


prog_qual_r 


prog_qual_rw 


prog_qual_w 


stop_br 


stop_call 


stop_cnt 


stop_data 


stop_disc 


stop_emu0 


Menu > 
Dialog Box 


Count > 
Event counter 


Count > 
Pipeline count 


Count > 
Program bus 


Count > 
Return taken 


Break — Data bus: 
Address field 


Count/Break > 
Data bus: Read 


Count/Break > 
Data bus: Access 


Count/Break > 
Data bus: Write 


Break > 
Program bus: 
Address field 


Break > 
Program bus: Fetch 


Count/Break > 
Program bus: Read 


Count/Break > 
Program bus: Ac- 
cess 


Count/Break > 
Program bus: Write 


Break > 
Branch taken 


Break > 
Call taken 


Count > 
Break when < 0 


Break — Data bus 
Break > 
Discontinuity 


Break > 
EMUO driven low 
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Table A-1. The Analysis Commands Found in the analysis.cmd File (continued) 


Description 


Load the analysis counter 
Count CPU pipeline execution 
clocks 


Count any program address 
accesses 


Count any returns from an 
interrupt/trap detected 


Set a breakpoint on a data 
address 


Data read qualifier 


Data read/write qualifier 


Data write qualifier 


Set a breakpoint on a program 
address 


Program instruction acquisition 


Program read qualifier 


Program read/write qualifier 


Program write qualifier 
Halt the processor when a 
branch is detected 


Halt the processor when a call is 
detected 


Halt the processor when the 
counter passes zero 


Halt the processor on a data bus 
access 


Halt any discontinuity 


Halt the processor when the 
EMUO pin is low 
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Page 


A-6 


A-8 


A-8 


A-8 


A-8 


A-8 


A-5 


A-6 


A-7 


A-7 


A-3 
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Table A-1. The Analysis Commands Found in the Analysis.cmd File (continued) 


Menu —> 

Command Dialog Box Description 

stop_emu1 Break > Halt the processor when the 
EMU14 driven low EMU1 pin is low 

stop_intr Break > Halt the processor when an 
Interrupt/trap taken interrupt/trap is detected 

stop_off none Disable break events 

stop_pclk Break > Halt the processor on a pipeline 
Pipeline clock clock (instruction fetched) 

stop_prog Break > Halt the processor on a program 
Program bus bus access 

stop_ret Break > Halt the processor when a return 
Return taken from an interrupt/trap is detected 


Page 
A-7 


A-7 


A-7 
A-7 


A-6 


A-7 


In addition to these predefined commands, you can create your own by using 
the ALIAS and EVAL commands. Refer to Sections 5.5 (page 5-21) and 8.2 
(page 8-2) for more information on ALIAS and EVAL. The following subsec- 


tions briefly describe the use of the analysis commands. 


Enabling the analysis interface 


Enabling the analysis interface is simply a matter of typing ina command. The 


basic syntax for this command is: 
asys_on 
To disable the analysis interface, enter: 


asys_off 


Enabling the EMUO0/1 pins 


A-4 


To set the EMU0/1 pins to output or to use the external counter, enter the ap- 


propriate command: 


To do this... Enter this... 
Set the EMUO pin to output asys_emu0out 
Set the EMU1 pin to output asys_emulout 
Use the external counter on the emulator asys_extcnt 
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Enabling event counting 


To load or reset the event counter (using the commands found in the 
analysis.cmd file), enter this command: 


cnt_load value 


Load value with a 1s complement of the number of times you want to count the 
specified event. For example, to stop the processor after ten instruction 
fetches have occurred, enter: 


cnt_load -10 Set the counter to count ten events and then stop 


—(count) 
cnt_ins Count the instruction fetches 
stop_cent Stop the processor when the counter reaches 0 


In this example, you must load the counter with a negative value because the 
evicnir register represents a 1s complement of the loaded value. 


To reset the internal event counter and count the number of instruction fetches 
detected, enter: 


cnt_load 0 Reset the counter 


cnt_ins Count the number of instruction fetches detected 
You can count only one event ata time. To count any of the other events, simply 
type in the appropriate command. Table A—2 shows the correct command for 
counting each of the nine events. 


Table A—2. The Analysis Commands 
Command 
cnt_br 
cnt_call 
cnt_clock 
cnt_data 
cnt_ins 


cnt_intr 


cnt_pclk 


cnt_prog 


cnt_ret 


Menu Selection 
Branch taken 


Call taken 

CPU clock 
Data bus 
Instruction fetch 


Interrupt/trap 
taken 


Pipeline clock 


Program bus 


Return taken 


Description 
Count the number of branches detected 


Count the number of calls detected 
Count the number of CPU clock cycles 
Count the number of data cycles 

Count the number of instruction fetches 


Count the number of interrupts/traps 
detected 


Count the CPU pipeline execution clocks 


Count the number of program address 
accesses 


Count the number of returns from inter- 
rupts, traps, or subroutine calls 
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Setting breakpoints on a single program or data address 


The simplest events to detect are those that identify a single address. To define 
this type of event, follow the command with a C expression. For example, to 
set a program address breakpoint, enter: 


asys_on Turn the analysis interface on 
prog_brk_add main Set a program address breakpoint on 
function_name 

stop_prog Enable the processor to stop on the 
breakpoint condition 

run Run the program 
prog_brk_add My Function Set a new program address 
breakpoint on function_name2 

run Run to the new breakpoint 


The commands shown in bold represent the actual breakpoint commands 
used. Main and My_Function represent the addresses on which the processor 
will break. These function names can be replaced by specific address loca- 
tions. Table A-3 shows the breakpoint commands for setting single address 
breakpoints; their respective menu selections can be found in the Analysis 
Break Events dialog box. You can set breakpoints on any combination of these 
events. 


Table A-3. Breakpoint Commands for Program and Data Addresses 


Dialog Box 
Command Selection Description 
data_brk_add address Data bus Set a data breakpoint address 
prog_brk_add address Program Set a program breakpoint address 
bus 
stop_data Data bus Stop the processor when the data 
breakpoint condition executes 
stop_prog Program Stop the processor when the pro- 
bus gram breakpoint condition executes 


A-6 


Summary of Aliased Commands 


Breaking on event occurrences 


You can set conditions on various types of processor operations. To define 
these conditions or events, simply enter the command. For example, to stop 


the processor when it detects an interrupt or a call taken, enter: 


asys_on 


stop_intr 


stop_call 


Turn the analysis interface on 


Enable the processor to stop when it 
detects an interrupt 


Enable the processor to stop when it 
detects a call taken 


Table A—4 shows the commands for stopping the processor when an event oc- 
curs. You can set breakpoints on any combination of these events. 


Table A-4. Breakpoint Commands for Event Occurrences 


Command Menu Selection Description 

stop_br Branch taken Stop the processor when a branch is 
taken 

stop_call Call taken Stop the processor when a call is taken 

stop_disc Discontinuity Stop the processor with any discontinu- 
ity 

stop_emu0 EMUO drivenlow _ Stop the processor when the EMU pin 
reaches a logic low of zero 

stop_emu1 EMU1 drivenlow _ Stop the processor when the EMU pin 
reaches a logic low of one 

stop_intr Interrupt/trap Stop the processor when an interrupt is 

taken detected 

stop_off none Disable break events 

stop_pclk Pipeline clock Stop the processor on a pipeline clock 
(instruction fetched) 

stop_ret Return taken Stop the processor when a return from 


an interrupt, branch, or call occurs 
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Qualifying on a read or a write 


Data and program accesses can be qualified, depending on whether the 
memory cycle is a read or write: 


go function_name 


data_qual_w 


data_brk_add data_symbol 


cnt_data 


run 


Run to the beginning of the function 
function_name 


Look only at writes 
Set a data address breakpoint 


Enable the processor to count any 
writes to the specified data access 


Count the number of any writes to 
data_symbol 


This example sets a data address breakpoint that counts only when a write is 
detected. Table A-5 shows the qualifier commands for data and program 
break events. You can use only one of these commands at a time. 


Table A—5. Read and Write Qualifying Commands for Data and Program Accesses 


Command 


data_qual_r 
data_qual_rw 
data_qual_w 
prog_qual_iaq 
prog_qual_r 
prog_qual_rw 


prog_qual_w 
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Menu Selection 
Data bus: Read 


Data bus: Access 
Data bus: Write 
Program bus: Fetch 
Program bus: Read 
Program bus: Access 


Program bus: Write 


Description 
Look only at data reads 


Look at both data reads and writes 
Look only at data writes 

Program instruction acquisition 
Look only at data reads 

Look at both data reads and writes 


Look only at data writes 
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Resetting the analysis interface 


Whenever you begin a new analysis session, you may want to define new pa- 
rameters or qualifier expressions. You can do this without manually 
deselecting each defined condition. Just enter the ASYS_ RESET command. 
To reset the analysis interface, type: 

asys_reset 


Cc OTT 
Note: 


To clear conditions or qualifier expressions previously defined via the Analy- 
sis menu, you must open the Analysis Count Events and Analysis Break 
Events dialog boxes and deselect each defined condition. 


A.2 Using the Analysis Registers 


By manipulating the analysis registers, you can customize commands for 
more complex instructions that do not exist on the Break or Count dialog 
boxes. Use the alias and evaluate commands to create your own commands. 
The basic syntax for creating customized analysis commands is: 


alias command_name, eval register name = code” 


For example, to create a new command for turning on the analysis interface, 
enter: 


alias analysis_on, "eval anaenbl = 1” 
To create a new command for counting branches detected, enter: 
alias cb, "e evtselt = 12” 


To create your own analysis commands, you must familiarize yourself with the 
thirteen analysis registers and how they work. The following subsections dis- 
cuss the analysis registers briefly. (The registers are in alphabetical order.) 
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anaenbl (Enable Analysis) 


You can enable and disable the analysis module by using the anaenbl register. 
Set the bit to 1 to enable or to 0 to disable. 


Bit Number Description 

enable analysis module 
reserved (set to 0) 
reserved (set to 0) 
enable external counter 
enable EMUO output 
enable EMU1 output 


akwNDM + © 


When you disable analysis, all registers except anaenbl retain their previous 
state. 


anastat (Analysis Status) 


The anastat register records the occurrence of enabled events. The status bits 
are defined below: 


Bit Number Definition 
call taken 
return from interrupt/trap/subroutine 
interrupt/trap taken 
branch taken 
pipeline clock 
program address 
data address 
discontinuity 
event counter passed zero 
EMUO detected low 
0 EMU1 detected low 


- OAN OA HRWN + CO 


Run commands will not interfere with the status bits, because they are cleared 
before command execution. 


Using the Analysis Registers 


datbrkp (Data Breakpoint Address) 


You can specify a breakpoint address for each of the major buses in the ’C5x 
path. When a valid bus cycle occurs and the bus value matches the breakpoint 
address, then a breakpoint condition can occur. 


datqual (Data Breakpoint Qualifier) 


The data breakpoint register has four qualifier bits. The qualifier definitions are 
shown below. 


Qualifier Code Definition 
0 read 

1 write 

2 reserved 
3 read/write 


evicntr (Event Counter) 


This register represents a true value in the ’C5x analysis module, which 
provides a 16-bit decrementing event counter. For convenience, the pseudo- 
register, EVT_cntr, provides a 1s complement of the evtcnir value. 


You can use the event counter in one of two ways: 


[_] Count the number of events detected. 
[__] Stop after n events have occurred. 


To count the number of events detected, load the counter with its maximum 
value —1, or OxXFFFF. The following example loads the counter and counts the 


instructions. 
cnt_load 0 Reset the counter 
cent_ins Count the number of instruction fetches detected 


The EVT_cnitr register will display the number of events detected after reach- 
ing a stop condition. 
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To stop after a certain number of events, load the counter with the number of 
events you want to occur before setting a breakpoint. The following example 
counts ten events and then stops. 


cnt_load -10 Set the counter to count ten events and then stop 

—(count) 
cnt_ins Count instruction fetches 
stop_cnt Stop the processor when the counter reaches 0 


If a software breakpoint halts the processor before the counter reaches zero, 
then the CNT_valu (displayed in the WATCH window) will contain the number 
of events remaining. 


ae, 
Note: 


When CPU clock cycles are counted, the event counter includes startup and 


latency cycles. 
| 


evtselt (Select the Event for Counting) 


The ’C5x can count ten types of events; however, only one event can be 
counted at a time. The count select codes are defined below. 


Select Code Definition 

0 CPU clocks 

1-7 not used 

8 instruction fetched 

9 call taken 

10 return from interrupt/trap/subroutine 
11 interrupt/trap taken 

12 branch taken 

13 pipeline clocks 

14 program address breakpoints 
15 data address breakpoints 


hbpenbl (Select Hardware Breakpoints) 


Using the Analysis Registers 


By setting the appropriate enable bit to 1 in the hbpenbl register, the ’C5x can 
break on multiple events. Setting the bit to 0 disables the breakpoint and clears 
the register. The breakpoint enable bits are defined below. 


Bit Number 


- OAN OA HRWN + CO 


oO 


pgabrkp (Program Address Breakpoint) 


Definition 

call taken 

return from interrupt/trap/subroutine 
interrupt/trap taken 
branch taken 

pipe clock 

program address 
data address 
discontinuity 

counter passing zero 
EMUO detected low 
EMU1 detected low 


You can specify a breakpoint address for each of the major buses in the ’C5x 
path. When a valid bus cycle occurs and the bus value matches the breakpoint 
address, then a breakpoint condition can occur. 


pgaqual (Program Breakpoint Qualifier) 


The data breakpoint register has four qualifier bits. The qualifier definitions are 


shown below. 


Qualifier Code 
0 


{ 
2 
3 


Definition 

read 

write 

program instruction acquisition 
read/write 


Customizing the Analysis Interface A-13 


Using the Analysis Registers 


ptrace0/ptrace1/ptrace2 (Discontinuity Trace Samples 0-2) 


Example A-1. 


A program discontinuity occurs when the program addresses fetched by the 
processor become nonsequential as a result of branches, interrupts, and simi- 
lar events. The ’C5x provides three levels of discontinuity trace to aid in pro- 
gram flow analysis: 


Register 
ptraceO 
ptrace1 
ptrace2 


Name 

discontinuity trace sample 0 
discontinuity trace sample 1 
discontinuity trace sample 2 


Program Discontinuity 
Address 


300A 
300B 
300C 
300E 
300F 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 


QU roman OB WBNHEHR OO 


Code 
nop 
nop 
b dcon2 
nop 
nop 
nop 
dcon2: nop 


b dconl 


dconl: nop 


nop 


Description 

traces the current code segment 
traces the previous code segment 
traces the oldest code segment 


Comment 


discontinuity occurs 
branch from 


branch to 


discontinuity occurs 
branch from 


branch to 


Stepping through the code starting at address 0x300A with ptrace0/1/2 initial- 
ized to zero, the trace buffer will show the following: 


[(_} Following the first branch (b dcon2), the trace contains the following val- 
ues: 


P 
P 
P 


RAC] 


E2 


RAC] 


Ei 1 


RAC] 


EO 


0x0000 


0x300E _ /ast instruction fetched before the branch 
0x3011 branch to address (dcon2) 


[(_} Following the second branch (b dcon1), the trace contains the following 


values: 


IP 
P. 
iP 


RAC] 


E2 


RACI 


E1 


RAC] 


EO 


0x3011 discontinuity from the oldest code segment 
0x3017 discontinuity from the previous code segment 
0x301A current code segment 
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What the Debugger Does 
During Invocation 


In some circumstances, you may find it helpful to know the steps that the 
debugger goes through during the invocation process. These are the steps, 
in order, that the debugger performs. Note that the PDM executes the first step. 
(For more information on the environment variables mentioned below, refer to 
your installation guide.) 


1) Establishes the connection between the processor name that you provide 
and the actual processor. 


2) Reads options from the command line. 


3) Reads any information specified with the D_OPTIONS environment vari- 
able. 


4) Reads information from the D_DIR and D_SRC environment variables. 
5) Looks for the init.clr screen configuration file. 


(The debugger searches for the screen configuration file in directories 
named with D_DIR.) 


6) Initializes the debugger screen and windows but initially displays only the 
COMMAND window. 


7) Finds the batch file that defines your memory map by searching in directo- 
ries named with D_DIR. The debugger expects this file to set up the 
memory map and follows these steps to look for the batch file: 


a) When you invoke the debugger, it checks to see if you’ve used the -t 
debugger option. If it finds the -t option, the debugger reads and 
executes the specified file. 


b) Ifyou don’t use the -t option, the debugger looks for the default initial- 
ization batch file called init.cmd. If the debugger finds this file, it reads 
and executes the commands. 


8) Loads any object filenames specified with D_ OPTIONS or specified on the 
command line during invocation. 


9) Determines the initial mode (auto, assembly, or mixed) and displays the 
appropriate windows on the screen. 


At this point, the debugger is ready to process any commands that you enter. 


B-1 


B-2 
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Describing Your Target System 
to the Debugger 


In order for the debugger to understand how you have configured your target 
system, you must supply a file for the debugger to read. 


_] If you’re using an emulation scan path that contains only one ’C5x and no 
other devices, you can use the board.dat file that comes with the ’C5x 
emulator kit. This file describes to the debugger the single ’C5x in the scan 
path and gives the ’C5x the name CPU_A. Since the debugger automati- 
cally looks for a file called board.dat in the current directory and in the di- 
rectories specified with the D_DIR environment variable, you can skip this 
appendix. 


[_] If you plan to use a different target system, you must follow these steps: 
Step 1: Create the board configuration text file. 


Step 2: Translate the board configuration text file to a binary, structured 
format so that the debugger can read it. 


Step 3: Specify the formatted configuration file when invoking the de- 
bugger. 


These steps are described in this appendix. 


Topic Page 


C.1 Step 1: Create the Board Configuration Text File C-2 


C.2 Step 2: Translate the Configuration File to a Debugger-Readable 
Format C-5 


C.3 Step 3: Specify the Configuration File When Invoking 
the Debugger C-5 


Step 1: Create the Board Configuration Text File 


C.1 Step 1: Create the Board Configuration Text File 


Example C-1. 


C-2 


To describe the emulation scan path of your target system to the debugger, you 
must create a board configuration file. The file consists of a series of entries, 
each describing one device on your scan path. You must list, in order, the indi- 
vidual devices on your system in the board configuration file for the debugger 
to work. The text version of the configuration file will be referred to as board.cfg 
in this book. 


Example C—1 shows a board.cfg file that describes a possible ’C5x device 
chain. It lists six octals named A1—A6, followed by five ’C5x devices named 


CPU_A, CPU_B, CPU_C, CPU_D, and CPU_E. 


A Sample 'C5x Device Chain 


(a) A sample board.cfg file 


Device Name 


"Ry" 


;the first device nearest TDO 


nee 
or 
ee 
er 
ae 


” CPU_A” 
u” CPU_B ” 


wu” CPU_C” 
wu" CPU_D” 
“CPU_E” 


(b) A sample ’C5x device chain 


Device Type 


BYPASS08 


BYPASSO08 
BYPASSO08 
BYPASSO8 
BYPASSO8 
BYPASSO8 
TI320C5x 
TI320C5x 
TI320C5x 
TI320C5x 
TI320C5x 


Comments 


7 (test data out) 
;the next device nearest TDO 


;the first ’C5x 


;the last ’C5x nearest TDI 
7 (test data in) 


Step 1: Create the Board Configuration Text File 


The order in which you list each device is important. The emulator scans the 
devices, assuming that the data from one device is followed by the data of the 
next device on the chain. Data from the device that is closest to the emulation 
header’s TDO reaches the emulator first. Moreover, in the board.cfg file, the 
devices should be listed in the order in which their data reaches the emulator. 
For example, the device whose data reaches the emulator first is listed first in 
the board.cfg file; the device whose data reaches the emulator last is listed last 
in the board.cfg file. 


The board.cfg file can have any number of each of the three types of entries: 


[|_| Debugger devices such as the ’C5x. These are the only devices that the 
debugger can recognize. 


|_| The Tl ACT8997 scan path linker, or SPL. The SPL allows you to have 
up to four secondary scan paths that can each contain debugger devices 
(‘C5xs) and other devices. 


[_] Other devices. These are any other devices in the scan path. For exam- 
ple, you can have devices such as the TI BCT 8244 octals that are used 
on the 'C4x PPDS board. These devices cannot be debugged and must 
be worked around or “bypassed” when trying to access the ’C5xs. 


Each entry in the board.cfg file consists of at least two pieces of data: 


J] The name of the device. The device name always appears first and is 
enclosed in double quotes: 
“device name” 


This is the same name that you use with the —n debugger option, which 
tells the debugger the name of the ’C5x. The device name can consist of 
up to eight alphanumeric characters or underscore characters and must 
begin with an alphabetic character. 


| The type of the device. The debugger supports the following device 
types: 


HM TI320C5x is an example of a debugger-device type. TI320C5x 
describes the 'C5x. TI320C4x describes the ’C4x. 


M@ SPL specifies the scan path linker and must be followed by four sub- 
paths, as in this syntax: 


"device name” SPL {subpath0} {subpath1} {subpath2 {subpath3} 


Each subpath can contain any number of devices. However, an SPL 
subpath cannot contain another SPL. 
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mM BYPASS## describes devices other than the debugger devices or 
SPL. The ## is the hexadecimal number that describes the number of 
bits in the device’s JTAG instruction register. For example, Tl BCT 
8244 octals have a device type of BYPASS08. 


Example C-—2 shows a file that contains an SPL. 


Example C-2. A board.cfg File Containing an SPL 


Device Name Device Type Commenis 


WRI" BYPASSO8 ;the first device nearest TDO 
WR BYPASSO8 
“CPULA” TI320C5x the first. “Csx 
HUB” SPL ;the scan path linker 
{ ;first subpath 
"Bi" BYPASSO8 
"B22" BYPASSO8 
*CPU_B” TI3S20C5x ;the second 'C5x 
} 
{ ;second subpath 
"CL" BYPASS08 
"C2" BYPASSO08 
"CPU_C” TI320C5x ;the third '’C5x 
} 
{ ;third subpath (contains nothing) 
} 
{ ;fourth subpath 
"DL" BYPASSO8 
"D2" BYPASSO8 
"CPU_D” TIS20C5x ;the fourth ’C5x 
} 
*CPULE” TI320C5x ;the last ’C5x nearest TDI 


Note: The indentation in the file is for readability only. 
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C.2 Step 2: Translate the Configuration File to a Debugger-Readable Format 


After you have created the board.cfg file, you must translate it from text toa 
binary, conditioned format so that the debugger can understand it. To translate 
the file, use the composer utility that is included with the emulator kit. At the 
system prompt, enter the following command: 


composer [input file [output file] | 


_] The input file is the name of the board.cfg file that you created in step 1; 
ifthe file isn’t in the current directory, you must supply the entire pathname. 
If you omit the input filename, the composer utility looks for a file called 
board.cfg in your current directory. 


(_} The output file is the name that you can specify for the resulting binary file; 
ideally, use the name board.dat. If you want the output file to reside in a 
directory other than the current directory, you must supply the entire path- 
name. If you omit an output filename, the composer utility creates a file 
called board.dat and places it in the current directory. 


To avoid confusion, use a .cfg extension for your text filenames and a .dat ex- 
tension for your binary filenames. If you enter only one filename on the com- 
mand line, the composer utility assumes that it is an input filename. 


C.3 Step 3: Specify the Configuration File When Invoking the Debugger 


When you invoke a debugger (either from the PDM or at the system prompt), 
the debugger must be able to find the board.dat file so that it knows how you 
have set up your scan path. The debugger looks for the board.dat file in the 
current directory and in the directories named with the D_DIR environment 
variable. 


If you used a name other than board.dat or if the board.dat file is not in the cur- 
rent directory nor in a directory named with D_DIR, you must use the -f option 
when you invoke the debugger. The —f option allows you to specify a board 
configuration file (and pathname) that will be used instead of board.dat. The 
format for this option is: 


-f filename 
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Debugger and PDM Messages 


This appendix contains an alphabetical listing of the progress and error mes- 
sages that the debugger or PDM might display in the display area of the COM- 
MAND window or in the PDM display area. Each message contains both a de- 
scription of the situation that causes the message and an action to take if the 
message indicates a problem or error. 


Topic Page 
D.1 Associating Sound With Error Messages D-2 
D.2 Alphabetical Summary of Debugger Messages D-2 
D.3 Alphabetical Summary of PDM Messages D-22 
D.4 Additional Instructions for Expression Errors D-26 
D.5 Additional Instructions for Hardware Errors D-26 
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Associating Sound With Error Messages / Alphabetical Summary of Debugger Messages 


D.1 Associating Sound With Error Messages 


You can associate a beeping sound with the display of error messages. To do 
this, use the SOUND command. The format for this command is: 


sound {on | off} 


By default, no beep is associated with error messages (SOUND OFF). The 
beep is helpful if the COMMAND window is hidden behind other windows. 
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‘]’ expected 


Description This is an expression error—it means that the parameter 
contained an opening bracket symbol “[’ but didn’t contain a 
closing bracket symbol “]”. 


Action See Section D.4 (page D-26). 


‘)’ expected 


Description This is an expression error—it means that the parameter 
contained an opening parenthesis symbol “(” but didn’t con- 
tain a closing parenthesis symbol “)”. 


Action See Section D.4 (page D-26). 


Aborted by user 


Description The debugger halted a long COMMAND display listing (from 
WHATIS, DIR, ML, or BL) because you pressed the key. 


Action None required; this is normal debugger behavior. 
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Breakpoint already exists at address 


Description 


Action 


During single-step execution, the debugger attempted to set 
a breakpoint where one already existed. (This isn’t necessari- 
ly a breakpoint that you set—it may have been an internal 
breakpoint that was used for single-stepping). 


None should be required; you may want to reset the program 
entry point (RESTART) and reenter the single-step 
command. 


Breakpoint table full 


Description 


Action 


200 breakpoints are already set, and there was an attempt to 
set another. The maximum limit of 200 breakpoints includes 
internal breakpoints that the debugger may set for 
single-stepping. Under normal conditions, this should not be 
a problem; it is rarely necessary to set this many breakpoints. 


Enter a BL command to see where breakpoints are set in your 
program. Use the BR command to delete all software break- 
points, or use the BD command to delete individual software 
breakpoints. 


Cannot allocate host memory 


Description 


Action 


This is a fatal error—it means that the debugger is running out 
of memory. 


You might try invoking the debugger with the —v option so that 
fewer symbols may be loaded. Or you might want to relink 
your program and link in fewer modules at a time. 


Cannot allocate system memory 


Description 


Action 


This is a fatal error—it means that the debugger is running out 
of memory. 


You might try invoking the debugger with the —v option so that 
fewer symbols may be loaded. Or you might want to relink 
your program and link in fewer modules at a time. 
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Cannot change directory 


Description 


Action 


The directory name specified with the CD command either 
doesn’t exist or is not in the current or auxiliary directories. 


Check the directory name that you specified. If this is really 
the directory that you want, re-enter the CD command and 
specify the entire pathname for that directory (for example, 
specify C:\c5xhlil, not just c5xhil). 


Cannot detect target power 


Description 


Action 


This hardware error occurs after the emurst command is re- 
set. Follow the steps described below and then restart your 
emulator. 


Check the emulator board to be sure it is installed snugly. 


[_.] Check the cable connecting your emulator and target 
system to be sure it is not loose. 


Check your target board to be sure it is getting the correct 
voltage. 


rupted. 


L} 
[| Check your emulator scan path to be sure it is uninter- 
L} 


Ensure that your port address is set correctly: 


HM Check to be sure the —p option used with the D_OP- 
TIONS environment variable matches the I/O ad- 
dress defined by your switch settings. (Refer to the 
TMS320C5x Emulator Installation Guide for more in- 
formation.) 


HM Check to see if you have a conflict in address space 
with another bus setting. If you have a conflict, 
change the switches on your board to one of the alter- 
nate settings listed in the installation guide. Modify 
the —p option of the D_OPTIONS environment vari- 
able to reflect the change in your switch settings. 


Cannot edit field 


Description 


Action 


D-4 


Expressions that are displayed in the WATCH window cannot 
be edited. 


If you attempted to edit an expression in the WATCH window, 
you may have actually wanted to change the value of a sym- 
bol or register used in the expression. Use the ? or EVAL 
command to edit the actual symbol or register. The expres- 
sion value will automatically be updated. 
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Cannot find/open initialization file 


Description 


Action 


The debugger can’t find the init.cmd file. 


Be sure that init.cmd is in the appropriate directory. If it isn’t, 
copy it from the debugger product diskette. If the file is already 
in the correct directory, verify that the D_DIR environment 
variable is set up to identify the directory. See Setting Up the 
Debugger Environment in the appropriate installation guide. 


Cannot halt the processor 


Description 


Action 


This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Exit the debugger. Invoke the autoexec or initdb.bat file; then 
invoke the debugger again. 


Cannot initialize target system 


Description 


Action 


This error occurs while you are invoking the debugger with the 
emulator. Any combination of events may cause this error to 
occur. 


Check the cable connecting the emulator to the target system 
to be sure it is not loose. 


[_] Ensure that your port address is set correctly: 


HM Check to be sure the —-p option used with the D_OP- 
TIONS environment variable matches the I/O ad- 
dress defined by your switch settings. 


M@ Check to see if you have a conflict in address space 
with another bus setting. If you have a conflict, 
change the switches on your board to one of the alter- 
nate settings listed in the installation guide. Modify 
the —p option of the D_OPTIONS environment vari- 
able to reflect the change in your switch settings. 


[_} Check the end of your autoexec.bat or initdb.bat file for 
the emurst.exe command. Execute this command after 
powering up the target board. 


For more details, refer to the TMS320C5x Emulator Installa- 
tion Guide. 
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Cannot initialize the EVM 


Description 


Action 


This error occurs while you are invoking the debugger with the 
EVM. Any combination of events may cause this error to oc- 
cur. 


Check the EVM board to be sure it is installed snugly. 
(_] Ensure that your port address is set correctly: 


HM Check to be sure the —p option used with the D_OP- 
TIONS environment variable matches the I/O ad- 
dress defined by your switch settings. 


HM Check to see if you have a conflict in address space 
with another bus setting. If you have a conflict, 
change the switches on your board to one of the alter- 
nate settings listed in the installation guide. Modify 
the —p option of the D-OPTIONS environment vari- 
able to reflect the change in your switch settings. 


For more details, refer to the TMS320C5x Evaluation Module 
Installation Guide. 


Cannot map into reserved memory: ? 


Description 


Action 


The debugger tried to access unconfigured/reserved/nonex- 
istent memory. 


Remap the reserved memory accesses. 


Cannot map port address 


Description 


Action 


You attempted to do a connect/disconnect on an illegal port 
address. 


Be sure that you are connecting to or disconnecting from an 
address that is mapped in as an input, output, or I/O port. 


Cannot open config file 


Description 


Action 


The SCONFIG command can’t find the screen-customization 
file that you specified. 


Be sure that the filename was typed correctly. If it wasn’t, 
re-enter the command with the correct name. If it was, 
re-enter the command and specify full path information with 
the filename. 
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Cannot open “filename” 


Description 


Action 


The debugger attempted to show filename in the FILE win- 
dow but could not find the file. 


Be sure that the file exists as named. If it does, enter the USE 
command to identify the file’s directory. 


Cannot open object file: “filename” 


Description 


Action 


The file specified with the LOAD, SLOAD, or RELOAD 
command is not an object file that the debugger can load. 


Be sure that you’re loading an actual object file. Be sure that 
the file was linked (you may want to run dspcl again to create 
an executable object file). 


Cannot open new window 


Description 


Action 


A maximum of 127 windows can be open at once. The last 
request to open a window would have made 128, which isn’t 
possible. 


Close any unnecessary windows. Windows that can be 
closed include WATCH, CALLS, DISP, and additional 
MEMORY windows. To close the WATCH window, enter WD. 
To close the CALLS, DISP, or a MEMORY window, make the 
desired window active and press 4). 


Cannot read processor status 


Description 


Action 


This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Exit the debugger. Invoke the autoexec or initdb.bat file, then 
invoke the debugger again. If you are using the emulator, 
check the cable connections, also. 


Cannot reset the processor 


Description 


Action 


This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Exit the debugger. Invoke the autoexec or initdb.bat file, then 
invoke the debugger again. If you are using the emulator, 
there may be a problem with the target system; check the 
cable connections. 


Debugger and PDM Messages D-7 


Alphabetical Summary of Debugger Messages 


D-8 


Cannot restart processor 


Description If a program doesn’t have an entry point, then RESTART 
won't reset the PC to the program entry point. 


Action Don’t use RESTART if your program doesn’t have an explicit 
entry point. 


Cannot set/verify breakpoint at address 


Description Either you attempted to set a breakpoint in read-only or 
protected memory, or there are hardware problems with the 
target system or EVM. This may also happen when you en- 
able or disable on-chip memory while using breakpoints. 


Action Check your memory map. If the address that you wanted to 
breakpoint wasn’t in ROM, see Section D.5 (page D-26). 


Cannot step 
Description There is a problem with the target system. 


Action See Section D.5 (page D-26). 


Cannot take address of register 


Description This is an expression error. C does not allow you to take the 
address of a register. 


Action See Section D.4 (page D-26). 


Command “cma” not found 
Description The debugger didn’t recognize the command that you typed. 


Action Re-enter the correct command. Refer to Chapter 13 or the 
Quick Reference Card for a list of valid debugger commands. 


Command timed out, emulator busy 
Description There is a problem with the target system. 


Action See Section D.5 (page D-26). 
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Conflicting map range 


Description 


Action 


A block of memory specified with the MA command overlaps 
an existing memory map entry. Blocks cannot overlap. 


Use the ML command to list the existing memory map; this will 
help you find that existing block that the new block would 
overlap. If the existing block is not necessary, delete it with the 
MD command and reenter the MA command. If the existing 
block is necessary, reenter the MA command with parame- 
ters that will not overlap the existing block. 


Corrupt call stack 


Description 


Action 


The debugger tried to update the CALLS window and 
couldn't. This may be because a function was called that 
didn’t return. Or it could be that the program stack was over- 
written in target memory. Another reason you may have this 
message is that you are debugging code that has optimiza- 
tion enabled (for example, you did not use the —g compile 
switch); if this is the case, ignore this message—code execu- 
tion is not affected. 


If your program called a function that didn’t return, then this is 
normal behavior (as long as you intended for the function not 
to return). Otherwise, you may be overwriting program 
memory. 


Emulator I/O address is invalid 


Description 


Action 


The debugger was invoked with the —p option, and an invalid 
port address was used. 


For valid port address values, refer to the TMS320C5x Emu- 
lator Installation Guide. 


Error in expression 


Description 
Action 


This is an expression error. 
See Section D.4 (page D-26). 


Execution error 


Description 
Action 


There is a problem with the target system. 
See Section D.5 (page D-26). 
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File already tied to port 


Description You attempted to connect to an address that already has afile 
connected to it. 


Action Connect the file to a mapped port that is not connected to a 
file. 


File already tied to this pin 


Description You attempted to connect an input file to an interrupt pin that 
already has a file connected to it. 


Action Use the PINC command to connect the file to another inter- 
rupt pin that is not connected to a file. 


File does not exist 
Description The port file could not be opened for reading. 


Action Be sure that the file exists as named. If it does, enter the USE 
command to identify the file’s directory. 


Files must be disconnected from ports 


Description You attempted to delete a memory map that has files con- 
nected to it. 


Action You must disconnect a port with the MI command before you 
can delete it from the memory map. 


File not found 


Description The filename specified for the FILE command was not found 
in the current directory or any of the directories identified with 
D_SRC. 


Action Be sure that the filename was typed correctly. If it was, reenter 
the FILE command and specify full path information with the 
filename. 
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File not found : “filename” 


Description The filename specified for the LOAD, RELOAD, SLOAD, or 
TAKE command was not found in the current directory or any 
of the directories identified with D_SRC. 


Action Be sure that the filename was typed correctly. If it was, 
re-enter the command and specify full path information with 
the filename. 


File too large (filename) 


Description You attempted to load a file that was more than 65,518 bytes 
long. 


Action Try loading the file without the symbol table (SLOAD), or use 
dsplnk to relink the program with fewer modules. 


Float not allowed 


Description This is an expression error—a floating-point value was used 
incorrectly. 


Action See Section D.4 (page D-26). 


Function required 


Description The parameter for the FUNC command mustbe the name ofa 
function in the program that is loaded. 


Action Re-enter the FUNC command with a valid function name. 


Illegal addressing mode 
Description An illegal ’C5x addressing mode was encountered. 


Action Refer to the TMS320C5x User’s Guide for valid addressing 
modes. 


Illegal cast 


Description This is an expression error—the expression parameter uses 
a cast that doesn’t meet the C language rules for casts. 


Action See Section D.4 (page D-26). 
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Illegal control transfer instruction 


Description The instruction following a delayed branch/call instruction 
was modifying the program counter. 


Action Modify your source code. 


Illegal left hand side of assignment 


Description This is an expression error—the lefthand side of an assign- 
ment expression doesn’t meet C language assignment rules. 


Action See Section D.4 (page D-26). 


Illegal memory access 
Description Your program tried to access unmapped memory. 


Action Modify your source code. 


Illegal opcode 
Description An invalid ’C5x instruction was encountered. 


Action Modify your source code. 


Illegal operand of & 


Description This is an expression error—the expression attempts to take 
the address of an item that doesn’t have an address. 


Action See Section D.4 (page D-26). 


Illegal pointer math 


Description This is an expression error—some types of pointer math are 
not valid in C expressions. 


Action See Section D.4 (page D-26). 


Illegal pointer subtraction 


Description This is an expression error—the expression attempts to use 
pointers in a way that is not valid. 


Action See Section D.4 (page D-26). 
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Illegal structure reference 


Description This is an expression error—either the item being referenced 
as a structure is nota structure, or you are attempting to refer- 
ence a nonexistent portion of a structure. 


Action See Section D.4 (page D-26). 


Illegal use of structures 


Description This is an expression error—the expression parameter is not 
using structures according to the C language rules. 


Action See Section D.4 (page D-26). 


Illegal use of void expression 


Description This is an expression error—the expression parameter does 
not meet the C language rules. 


Action See Section D.4 (page D-26). 


Integer not allowed 


Description This is an expression error—the command did not accept an 
integer as a parameter. 


Action See Section D.4 (page D-26). 


Invalid address 
— Memory access outside valid range: address 


Description The debugger attempted to access memory at address, 
which is outside the memory map. 


Action Check your memory map to be sure that you access valid 
memory. 


Invalid argument 


Description One of the command parameters does not meet the require- 
ments for the command. 


Action Re-enter the command with valid parameters. Refer to the 
appropriate command description in Chapter 13. 
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Invalid attribute name 


Description 


Action 


The COLOR and SCOLOR commands accept a specific set 
of area names for their first parameter. The parameter 
entered did not match one of the valid attributes. 


Re-enter the COLOR or SCOLOR command with a valid area 
name parameter. Valid area names are listed in Table 10-2 
(page 10-3). 


Invalid color name 


Description 


Action 


The COLOR and SCOLOR commands accept a specific set 
of color attributes as parameters. The parameter entered did 
not match one of the valid attributes. 


Re-enter the COLOR or SCOLOR command with a valid color 
parameter. Valid color attributes are listed in Table 10-1 
(page 10-2). 


Invalid memory attribute 


Description 


Action 


The third parameter of the MA command specifies the type, or 
attribute, of the block of memory that MA adds to the memory 
map. The parameter entered did not match one of the valid 
attributes. 


Re-enter the MA command. Use one of the following valid 
parameters to identify the memory type: 


R, ROM, READONLY (read-only memory) 
W, WOM, WRITEONLY (write-only memory) 
RW, RAM (read/write memory) 
PROTECT (no-access memory) 
OPORT (I/O memory) 
IPORT (I/O memory) 
IOPORT (I/O memory) 
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Invalid object file 


Description 


Action 


Either the file specified with the LOAD, SLOAD, or RELOAD 
command is not an object file that the debugger can load, or it 
has been corrupted. 


Be sure that you’re loading an actual object file. Be sure that 
the file was linked (you may want to run dspcl again to create 
an executable object file). If the file you attempted to load was 
a valid executable object file, then it was probably corrupted; 
recompile, assemble, and link with dspcl. 


Invalid watch delete 


Description 


Action 


The debugger can’t delete the parameter supplied with the 
WD command. Usually, this is because the watch index 
doesn’t exist or because a symbol name was typed instead of 
a watch index. 


Re-enter the WD command. Be sure to specify the watch 
index that matches the item you'd like to delete (this is the 
number in the left column of the WATCH window). Remem- 
ber, you can’t delete items symbolically—you must delete 
them by number. 


Invalid window position 


Description 


Action 


The debugger can’t move the active window to the XY posi- 
tion specified with the MOVE command. Either the XY param- 
eters are not within the screen limits, or the active window 
may be too large to move to the desired position. 


You can use the mouse to move the window. 


(_] If you don’t have a mouse, enter the MOVE command 
without parameters; then use the arrow keys to move the 
window. When you're finished, you mustpress or@). 


_] Ifyou prefer to use the MOVE command with parameters, 
the minimum XY position is 0,1; the maximum position 
depends on which screen size you’re using. 
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Invalid window size 


Description The width and length specified with the SIZE or MOVE com- 
mand may be too large or too small. If valid width and length 
were specified, then the active window is already at the far 
right or bottom of the screen and so cannot be made larger. 


Action You can use the mouse to size the window. 


_j Ifyou don’t have amouse, enter the SIZE command with- 
out parameters; then use the arrow keys to move the win- 
dow. When you're finished, you must press or @). 


_] If you prefer to use the SIZE command with parameters, 
the minimum size is 4 by 3; the maximum size depends 
on which screen size you’re using. 


Load aborted 
Description This message always follows another message. 


Action Refer to the message that preceded Load aborted. 


Lost power (or cable disconnected) 


Description Either the target cable is disconnected, or the target system is 
faulty. 


Action Check the target cable connections. If the target seems to be 
connected correctly, see Section D.5 (page D-26). 


Lost processor clock 


Description Either the target cable is disconnected, or the target system is 
faulty. 


Action Check the target cable connections. If the target seems to be 
connected correctly, see Section D.5 (page D-26). 


Lval required 


Description This is an expression error—an assignment expression was 
entered that requires a legal left-hand side. 


Action See Section D.4 (page D-26). 
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Memory access error at address 


Description 


Action 


Either the processor is receiving a bus fault, or there are 
problems with target system memory. 


See Section D.5 (page D-26). 


Memory map table full 


Description 


Action 


Too many blocks have been added to the memory map. This 
will rarely happen unless blocks are added word by word 
(which is inadvisable). 


Stop adding blocks to the memory map. Consolidate any 
adjacent blocks that have the same memory attributes. 


Name “name” not found 


Description 


Action 


The command cannot find the object named name. 


If name is a symbol, be sure that it was typed correctly. If it 
wasn’t, reenter the command with the correct name. If it was, 
then be sure that the associated object file is loaded. 


Nesting of repeats cannot exceed 100 


Description 


Action 


The debugger cannot simulate more than 100 levels of repeat 
nesting in an input data file. If this happens, the debugger dis- 
connects the input file from the pin. 


Correct the input file so that the data does not include nesting 
repetition exceeding 100. Use the PINC command to recon- 
nect the input file to the desired pin. 
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No file connected to this pin 


Description You tried to disconnect the input file from a pin that was not 
previously connected to that pin. 


Action Use the PINL command to list all of the pins and the files con- 
nected to them. Use the PIND command to re-enter the cor- 
rect pinname and filename. 


Non-repeatable instruction 


Description The instruction following the RPT instruction is not a repeat- 
able instruction. 


Action Modify your code. 


Pinname not valid for this chip 


Description You attempted to connect or disconnect an input file to an 
invalid interrupt pin. 


Action Reconnect or disconnect the input file to an unused interrupt 
pin (INT1-INT4 or BIO). 


Pointer not allowed 
Description This is an expression error. 


Action See Section D.4 (page D-26). 


Processor is already running 


Description One of the RUN commands was entered while the debugger 
was running free from the target system. 


Action Enter the HALT command to stop the free run, then re-enter 
the desired RUN command. 
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Read not allowed for port 


Description You attempted to connect a file for input operation to an ad- 
dress that is not configured for read. 


Action Remap the port of correct the access in your source code. 


Register access error 


Description Either the processor is receiving a bus fault, or there are 
problems with target-system memory. 


Action See Section D.5 (page D-26). 


Specified map not found 


Description The MD command was entered with an address or block that 
is not in the memory map. 


Action Use the ML command to verify the current memory map. 
When using MD, you can specify only the first address of a 
defined block. 


Structure member not found 


Description This is an expression error—an expression references a non- 
existent structure member. 


Action See Section D.4 (page D-26). 


Structure member name required 


Description This is an expression error—a symbol name followed by a 
period but no member name. 


Action See Section D.4 (page D-26). 


Structure not allowed 


Description This is an expression error—the expression is attempting an 
operation that cannot be performed on a structure. 


Action See Section D.4 (page D-26). 
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Take file stack too deep 


Description 


Action 


Batch files can be nested up to 10 levels deep. Batch files can 
call other batch files, which can call other batch files, and so 
on. Apparently, the batch file that you are TAKEing calls batch 
files that are nested more than 10 levels deep. 


Edit the batch file that caused the error. Instead of calling 
another batch file from within the offending file, you may want 
to copy the contents of the second file into the first. This will 
remove a level of nesting. 


Too few instruction words in RPTB 


Description 


Action 


The length of repeat block was less than three instruction 
words. 


Modify your code. 


Too many breakpoints 


Description 


Action 


200 breakpoints are already set, and there was an attempt to 
set another. Note that the maximum limit of 200 breakpoints 
includes internal breakpoints that the debugger may set for 
single-stepping. Under normal conditions, this should not be 
a problem; it is rarely necessary to set this many breakpoints. 


Entera BL command to see where breakpoints are set in your 
program. Use the BR command to delete all software break- 
points or use the BD command to delete individual software 
breakpoints. 


Too many paths 


Description 


Action 


More than 20 paths have been specified cumulatively with the 
USE command, D_SRC environment variable, and —i debug- 
ger option. 


Don’t enter the USE command before entering another com- 
mand that has a filename parameter. Instead, enter the sec- 
ond command and specify full path information for the file- 
name. 
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Undeclared port address 


Description 


Action 


User halt 


Description 


Action 


You attempted to do a connect/disconnect on an address that 
isn’t declared as a port. 


Verify the address of the port to be connected or discon- 
nected. 


The debugger halted program execution because you 
pressed the key. 


None required; this is normal debugger behavior. 


Window not found 


Description 


Action 


The parameter supplied for the WIN command is not a valid 
window name. 


Re-enter the WIN command. Remember that window names 
must be typed in uppercase letters. Here are the valid window 
names; the bold letters show the smallest acceptable abbre- 
viations: 


CALLS CPU DISP 
COMMAND DISASSEMBLY FILE 
MEMORY PROFILE WATCH 


Write not allowed for port 


Description 


Action 


You attempted to connect a file for output operation to an ad- 
dress that is not configured for write. 


Either change the ’C5x software to write a port that is config- 
ured for write, or change the attributes of the port. 
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D.3 Alphabetical Summary of PDM Messages 


This section contains an alphabetical listing of the error messages that the 
PDM might display. Each message contains both a description of the situation 
that causes the message and an action to take. 


Note: 


If errors are detected in a TAKE file, the PDM aborts the batch file execution, 
and the file line number of the invalid command is displayed along with the 
error message. 


ss | 


Cannot communicate with “name” 


Description The PDM cannot communicate with the named debugger, be- 
cause the debugger either crashed or was exited. 


Action Spawn the debugger again. 


Cannot communicate with the child debugger 


Description This error occurs when you are spawning a debugger. The 
PDM was able to find the debugger executable file, but the de- 
bugger could not be invoked for some reason, and the com- 
munication between the debugger and PDM was never es- 
tablished. This usually occurs when you have a problem with 
your target system. 


Action Exit the PDM and go back though the installation instructions 
in the installation guide. Reinvoke the PDM and try to spawn 
the debugger again. 


Cannot create mailbox 


Description The PDM was unable to create a mailbox for the new debug- 
ger that you were trying to spawn; the PDM must be able to 
create a mailbox in order to communicate with each debug- 
ger. This message usually indicates a resource limitation (you 
have more debuggers invoked than your system can handle). 


Action If you have numerous debuggers invoked and you're not us- 
ing all of them, close some of them. If you are under a UNIX 
environment, use the ipcs command to check your message 
queues; use ipcrm to clean up the message queues. 
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Cannot open log file 


Description The PDM cannot find the filename that you supplied when you 
entered the DLOG command. 


Action Be sure that the file resides in the current directory or in one of 
the directories specified by the D_DIR environment vari- 
able. 


[_] Check to see if you mistyped the filename. 


Cannot open take file 


Description The PDM cannot find the batch filename supplied for the 
TAKE command. You will also see this message if you try to 
execute a batch file that does not have a .pdm extension. 


Action Be sure that the file resides in the current directory or in one of 
the directories specified by the D_DIR environment vari- 
able. 


[_] Check to see whether you mistyped the filename. 


[_]| Be sure that the batch filename has a .pdm extension. 


[_] Be sure that the file has executable rights. 


Cannot open temporary file 


Description The PDMis unable create a temporary file in the current direc- 
tory. 


Action Change the permissions of the current directory. 


Cannot seek in file 


Description While the PDM was reading a file, the file was deleted or mo- 
dified. 


Action Be sure that the files the PDM reads are not deleted or modi- 
fied during the read. 
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Cannot spawn child debugger 


Description The PDM couldn't spawn the debugger that you specified, be- 
cause the PDM couldn't find the debugger executable file 
(emu5x). The PDM will first search for the file in the current 
directory and then search the directories listed with the PATH 
statement. 


Action Check to see if the executable file is in the current directory or 
in adirectory that is specified by the PATH statement. Modify 
the PATH statement if necessary, or change the current direc- 
tory. 


Command error 


Description The syntax for the command that you entered was invalid (for 
example, you used the wrong options or arguments). 


Action Re-enter the command with valid parameters. 


Debugger spawn limit reached 


Description The PDM spawned the maximum number of debuggers that it 
can keep track of in its internal tables. The maximum number 
of debuggers that the PDM can track is 2048. However, your 
system may not have enough resources to support that many 
debuggers. 


Action Before trying to spawn an additional debugger, close any de- 
buggers that you don’t need to run. 


Illegal flow control 


Description One of the flow control commands (IF/ELIF/ELSE/ENDIF or 
LOOP/BREAK/CONTINUE/ENDLOOP) has an error. This 
error usually occurs when there is some type of imbalance in 
one of these commands. 


Action Check the flow command construct for such problems as an 
IF without an ENDIF, a LOOP without an ENDLOOP, or a 
BREAK that does not appear between a LOOP and an 
ENDLOOP. Edit the batch file that contains the problem flow 
command, or interactively re-enter the correct command. 


Alphabetical Summary of PDM Messages 


Input buffer overflow 


Description 


Action 


The PDM is trying to execute or manipulate an alias or shell 
variable that has been recursively defined. 


Use the SET and/or ALIAS commands to check the defini- 
tions of your aliases and system variables. Modify them as 
necessary. 


Invalid command 


Description 


Action 


The command that you entered was not valid. 


Refer to the command summary in Chapter 13, Summary of 
Commands and Special Keys, for a complete list of com- 
mands and their syntax. 


Invalid expression 


Description 


Action 


The expression that you used with a flow control command or 
the @ command is invalid. You may see specific messages 
before this one that provide more information about the prob- 
lem with the expression. The most common problem is the 
failure to use the $ character when evaluating the contents of 
a system variable. 


Check the expression that you used. Refer to Section 2.7, 
page 2-17, for more information about expression analysis. 


Invalid shell variable name 


Description 


Action 


The system variable name that you used the SET command 
to assign is invalid. Variable names can contain any alphanu- 
meric characters or underscore characters. 


Use a different name. 


Maximum loop depth exceeded 


Description 


Action 


The LOOP/ENDLOOP command that you tried to execute 
had more than 10 nested LOOP/ENDLOOP constructs. 
LOOP/ENDLOOP constructs can be nested up to 10 deep. 


Edit the batch file that contains the _LOOP/ENDLOOP 
construct, or re-enter the LOOP/ENDLOOP command inter- 
actively. 
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Maximum take file depth exceeded 


Description The batch file that you tried to execute with the TAKE com- 
mand called or nested more than 10 other batch files. The 
TAKE command can handle batch files that are nested up to 
10 deep. 


Action Edit the batch file. 


Unknown processor name “name” 


Description The processor name that you specified with the —g option ora 
processor name within a group that you specified with the —g 
option does not match any of the names of the debuggers that 
were spawned under the PDM. 


Action Be sure that you've correctly entered the processor name. 


D.4 Additional Instructions for Expression Errors 


Whenever you receive an expression error, you should re-enter the command 
and edit the expression so that it follows the C language expression rules. If 
necessary, refer to a C language manual such as The C Programming 
Language by Brian W. Kernighan and Dennis M. Ritchie. 


D.5 Additional Instructions for Hardware Errors 


If you continue to receive the messages that send you to this section, this indi- 
cates persistent hardware problems. 


[_] If a bus fault occurs, the emulator may not be able to access memory. 


[_.] The ’C5x must be reset before you can use the emulator. Most target sys- 
tems reset the ’‘C5x at power-up; your target system may not be doing this. 
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active window: The window that is currently selected for moving, sizing, 
editing, closing, or some other function. 


aggregate type: AC data type such as a structure or array in which a vari- 
able is composed of multiple variables, called members. 


aliasing: A method of customizing debugger commands; aliasing provides 
a shorthand method for entering often-used command strings. 


ANSI C: A version of the C programming language that conforms to the C 
standards defined by the American National Standards Institute. 


assembly mode: A debugging mode that shows assembly language code 
in the DISASSEMBLY and doesn’t show the FILE window, no matter 
what type of code is currently running. 


autoexec.bat: A batch file that contains DOS commands for initializing your 
PC. 


auto mode: A context-sensitive debugging mode that automatically 
switches between showing assembly language code in the 
DISASSEMBLY window and C code in the FILE window, depending on 
what type of code is currently running. 


batch file: One of two different types of files. One type contains DOS com- 
mands for the PC to execute. A second type of batch file contains debug- 
ger commands for the debugger to execute. The PC doesn’t execute 
debugger batch files, and the debugger doesn’t execute PC batch files. 


benchmarking: A type of program execution that allows you to track the 
number of CPU cycles consumed by a specific section of code. 


breakpoint: A point within your program where execution will halt because 
of a previous request from you. 


break event: An event that causes the processor to halt. 
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C: A high-level, general-purpose programming language useful for writing 
compilers and operating systems and for programming microproces- 
sors. 


CALLS window: A window that lists the functions called by your program. 


casting: A feature of C expressions that allows you to use one type of data 
as if it were a different type of data. 


children: Additional windows opened for aggregate types that are members 
of a parent aggregate type displayed in an existing DISP window. 


click: To press and release a mouse button without moving the mouse. 


CLK: A pseudoregister that shows the number of CPU cycles consumed 
during benchmarking. The value in CLK is valid only after you enter a 
RUNB command but before you enter another RUN command. 


code-display windows: Windows that show code, text files, or code- 
specific information. This category includes the DISASSEMBLY, FILES, 
and CALLS windows. 


COFF: Common Object File Format. An implementation of the object file 
format of the same name developed by AT&T. The TMS320 fixed-point 
DSP compiler, assembler, and linker use and generate COFF files. 


commandline: The portion of the COMMAND window where you can enter 
commands. 


command-line cursor: A block-shaped cursor that identifies the current 
character position on the command line. 


COMMAND window: A window that provides an area for you to enter com- 
mands and for the debugger to echo command entry, show command 
output, and list progress or error messages. 


CPUwindow: Awindow that displays the contents of ’C5x on-chip registers, 
including the program counter, status register, A-file registers, and B-file 
registers. 


current-field cursor: Ascreen icon that identifies the current field in the ac- 
tive window. 


cursor: Aniconon the screen (such as a rectangle or a horizontal line) that 
is used as a pointing device. The cursor is usually under mouse or 
keyboard control. 


Glossary 


data-display windows: Windows for observing and modifying various 
types of data. This category includes the MEMORY, CPU, DISP, and 
WATCH windows. 


D_DIR: An environment variable that identifies the directory containing the 
commands and files necessary for running the debugger. 


debugger: A window-oriented software interface that helps you to debug 
’°C5x programs running on a’C5x emulator, EVM, or simulator. 


disassembly: Assembly language code formed from the reverse-assembly 
of the contents of memory. 


DISASSEMBLY window: A window that displays the disassembly of 
memory contents. 


discontinuity: A state in which the addresses fetched by the debugger be- 
come nonsequential as a result of instructions that load the PC with new 
values, such as branches, calls, and returns. 


DISP window: A window that displays the members of an aggregate data 
type. 


display area: The portion of the COMMAND window or PDM window where 
the debugger echoes command entry, shows command output, and lists 
progress or error messages. 


D_OPTIONS: Anenvironment variable that you can use for identifying often- 
used debugger options. 


drag: To move the mouse while pressing one of the mouse buttons. 


dspcl: A shell utility that invokes the TMS320 fixed-point DSP compiler, 
assembler, and linker to create an executable object file version of your 
program. 


D SRC: An environment variable that identifies directories containing 
program source files. 


EGA: Enhanced Graphics Adaptor. An industry standard for video cards. 
EISA: Extended Industry Standard Architecture. A standard for PC buses. 
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emulator: A debugging tool that is external to the target system and pro- 
vides direct control over the ’C5x processor that is on the target system. 


emurst: A utility that resets the emulator. 


environment variable: A special system symbol that the debugger uses for 
finding directories or obtaining debugger options. 


EVM: Evaluation Module. A development tool that lets you execute and 
debug applications programs by using the ’C5x debugger. 


event: An operation performed in hardware such as branches, calls, and re- 
turn instructions. 


evmrst: A utility that resets the EVM. 


FILE window: A window that displays the contents of the current C code. 
The FILE window is intended primarily for displaying C code but can be 
used to display any text file. 


init.cmd: A batch file that contains debugger-initialization commands. If this 
file isn’t present when you first invoke the debugger, then all memory is 
invalid. 


initdb.bat: A batch file created to contain DOS commands to set up the 
debugger environment. 


/O switches: Hardware switches on the emulator or EVM board that identify 
the PC I/O memory space used for emulator-debugger or 
EVM-debugger communications. 


ISA: Industry Standard Architecture. A subset of the EISA standard. 


memory map: A map of memory space that tells the debugger which areas 
of memory can and can’t be accessed. 


MEMORY window: A window that displays the contents of memory. 


menu bar: A rowof pulldown menu selections found at the top of the debug- 
ger display. 
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mixed mode: Adebugging mode that simultaneously shows both assembly 
language code in the DISASSEMBLY window and C code in the FILE 
window. 


mouse cursor: A block-shaped cursor that tracks mouse movements over 
the entire display. 


open-collector output: An output circuit that actively drives both high and 
low logic levels. 


PC: Personal computer or program counter, depending on the context and 
where it’s used in this book: 1) In installation instructions or information 
relating to hardware and boards, PC means personal computer (as in 
IBM PC). 2) In general debugger and program-related information, PC 
means program counter, which is the register that identifies the current 
statement in your program. 


PDM: Parallel Debug Manager. A program used for creating and controlling 
multiple debuggers for the purpose of debugging code in a parallel- 
processing environment. 


point: To move the mouse cursor until it overlays the desired object on the 
screen. 


port address: The PC I/O memory space that the debugger uses for 
communicating with the emulator or EVM. The port address is selected 
via switches on the emulator or EVM board and communicated to the 
debugger with the —p debugger option. 


pulldown menu: A command menu that is accessed by name or with the 
mouse from the menu bar at the top of the debugger display. 


ripple-carry output signal: An output signal from a counter indicating that 
the counter has reached its maximum value. 


scalartype: ACtypeinwhichthe variable is a single variable, not composed 
of other variables. 
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scrolling: A method of moving the contents of a window up, down, left, or 
right to view contents that weren't originally shown. 


side effects: A feature of C expressions in which using an assignment 
operator in an expression affects the value of one of the components 
used in the expression. 


simulator: A development tool that simulates the operation of the ’C5x and 
lets you execute and debug applications programs by using the 'C5x de- 
bugger. 


single-step: A form of program execution that allows you to see the effects 
of each statement. The program is executed statement by statement; the 
debugger pauses after each statement to update the data-display 
windows. 


symbol table: A file that contains the names of all variables and functions 
in your ’C5x program. 


system shell: A utility invoked with the SYSTEM command, which makes 
it possible for the debugger to blank the debugger display and temporari- 
ly exit to the DOS prompt. This allows you to enter DOS commands or 
allows the debugger to display information resulting from a DOS com- 
mand. 


target system: A ’C5x board that works with the emulator; the emulator 
doesn’t contain a’C5x device, so it must use a’C5x target board. Usually, 
the target system is a board that you have designed; you use the emula- 
tor and debugger to help you debug your design. 


totem-pole output: An output circuit that actively drives both high and low 
logic levels. 


VGA: Video Graphics Array. An industry standard for video cards. 


WATCH window: A window that displays the values of selected expres- 
sions, symbols, addresses, and registers. 


window: A defined rectangular area of virtual space on the display. 
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Customizing the Analysis Interface 


The interface to the ’C5x analysis module is register-based. In most cases, the 
Analysis Count Events and Analysis Break Events dialog boxes provide a suf- 
ficient means of counting events and setting hardware breakpoints. In some 
cases, however, you may want to define more complex conditions for the pro- 
cessor to detect. Or, you may want to write a batch file that defines counting 
or breakpoint conditions. In either case, you can accomplish these tasks by 
accessing the analysis registers through the debugger. This appendix ex- 
plains how to access these registers. 


Topic Page 
A.1.| Summary of Aliased Commands A-2 
Enabling the analysis interface A-4 
Enabling the EMU0/1 pins A-4 
Enabling event counting A-5 
Setting breakpoints on a single program or data address A-6 
Breaking on event occurrences A-7 
Qualifying on a read or write A-8 
Resetting the analysis interface A-9 
A.2_ Using the Analysis Registers A-9 
anaenbl (Enable Analysis) A-10 
anastat (Analysis Status) A-10 
datbrkp (Data Breakpoint Address) A-11 
datqual (Data Breakpoint Qualifier) A-11 
evicntr (Event Counter) A-11 
eviselt (Select the Event for Counting) A-12 
hbpenbl (Select Hardware Breakpoints) A-13 
pgabrkp (Program Address Breakpoint) A-13 
pgaqual (Program Breakpoint Qualifier) A-13 
ptraceO/ptrace 1/ptrace2 (Discontinuity Trace Samples 0-2) A-14 


Summary of Aliased Commands 


A.1 Summary of Aliased Commands 


A basic set of analysis commands is defined in the analysis.cmd file supplied 
in your ’C5x debugger package. These commands, like the analysis dialog 
boxes, load the analysis registers with your specified values. You must TAKE 
the analysis.cmd file before you can use any of these commands. To do this, 
enter: 


take analysis.cmd 


By default, the debugger echoes the file to the output area of the COMMAND 
window. However, you can view the entire file by using the FILE command to 
display its contents in the FILE window. Table A—1 shows the predefined com- 
mands along with their menu equivalents. 


The aliased commands, created in the analysis.cmd file, are provided to help 
you familiarize yourself with the analysis registers and how they work. The 
aliases are simply a starting point for you to build upon to create your own com- 
mands. 


Table A—1. The Analysis Commands Found in the analysis.cmd File 


Menu —> 

Command Dialog Box Description Page 

asys_emuOout Emulator pins > Set EMUO pin to output A-4 
EMUO trigger out 

asys_emutout Emulator pins > Set EMU1 pin to output A-4 
EMUO trigger out 

asys_extcnt Emulator pins > Use the external counteronthe A-4 
External clock emulator 

asys_ off Analysis > Turn off the analysis interface A-4 
Enable/Disable 

asys_on Analysis > Turn on the analysis interface A-4 
Disable/Enable 

asys_reset none Reset the analysis interface A-9 

cnt_br Count > Count any branches detected A-5 
Branch taken 

cnt_call Count > Count any calls detected A-5 
Call taken 

cnt_clock Count > Count CPU clock cycles A-5 
CPU clock 

cnt_data Count > Count any data accesses A-5 
Data bus 

cnt_ins Count > Count any instructions fetched A-5 
Instruction fetch 

ent_intr Count > Count any interrupts/traps A-5 


Interrupt/trap taken 


detected 


Command 


cnt_load value 


cnt_pclk 


cnt_prog 


cnt_ret 


data_brk_add address 


or symbol name 


data_qual_r 


data_qual_rw 


data_qual_w 


prog_brk_add aa- 
dress or function 
name 


prog_qual_iaq 


prog_qual_r 


prog_qual_rw 


prog_qual_w 


stop_br 


stop_call 


stop_cnt 


stop_data 


stop_disc 


stop_emu0 


Menu > 
Dialog Box 


Count > 
Event counter 


Count > 
Pipeline count 


Count > 
Program bus 


Count > 
Return taken 


Break — Data bus: 
Address field 


Count/Break > 
Data bus: Read 


Count/Break > 
Data bus: Access 


Count/Break > 
Data bus: Write 


Break > 
Program bus: 
Address field 


Break > 
Program bus: Fetch 


Count/Break > 
Program bus: Read 


Count/Break > 
Program bus: Ac- 
cess 


Count/Break > 
Program bus: Write 


Break > 
Branch taken 


Break > 
Call taken 


Count > 
Break when < 0 


Break — Data bus 
Break > 
Discontinuity 


Break > 
EMUO driven low 
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Table A-1. The Analysis Commands Found in the analysis.cmd File (continued) 


Description 


Load the analysis counter 
Count CPU pipeline execution 
clocks 


Count any program address 
accesses 


Count any returns from an 
interrupt/trap detected 


Set a breakpoint on a data 
address 


Data read qualifier 


Data read/write qualifier 


Data write qualifier 


Set a breakpoint on a program 
address 


Program instruction acquisition 


Program read qualifier 


Program read/write qualifier 


Program write qualifier 
Halt the processor when a 
branch is detected 


Halt the processor when a call is 
detected 


Halt the processor when the 
counter passes zero 


Halt the processor on a data bus 
access 


Halt any discontinuity 


Halt the processor when the 
EMUO pin is low 
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A-8 
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A-5 


A-6 


A-7 


A-7 
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Table A-1. The Analysis Commands Found in the Analysis.cmd File (continued) 


Menu —> 

Command Dialog Box Description 

stop_emu1 Break > Halt the processor when the 
EMU14 driven low EMU1 pin is low 

stop_intr Break > Halt the processor when an 
Interrupt/trap taken interrupt/trap is detected 

stop_off none Disable break events 

stop_pclk Break > Halt the processor on a pipeline 
Pipeline clock clock (instruction fetched) 

stop_prog Break > Halt the processor on a program 
Program bus bus access 

stop_ret Break > Halt the processor when a return 
Return taken from an interrupt/trap is detected 


Page 
A-7 


A-7 
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In addition to these predefined commands, you can create your own by using 
the ALIAS and EVAL commands. Refer to Sections 5.5 (page 5-21) and 8.2 
(page 8-2) for more information on ALIAS and EVAL. The following subsec- 


tions briefly describe the use of the analysis commands. 


Enabling the analysis interface 


Enabling the analysis interface is simply a matter of typing ina command. The 


basic syntax for this command is: 
asys_on 
To disable the analysis interface, enter: 


asys_off 


Enabling the EMUO0/1 pins 
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To set the EMU0/1 pins to output or to use the external counter, enter the ap- 


propriate command: 


To do this... Enter this... 
Set the EMUO pin to output asys_emu0out 
Set the EMU1 pin to output asys_emulout 
Use the external counter on the emulator asys_extcnt 
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Enabling event counting 


To load or reset the event counter (using the commands found in the 
analysis.cmd file), enter this command: 


cnt_load value 


Load value with a 1s complement of the number of times you want to count the 
specified event. For example, to stop the processor after ten instruction 
fetches have occurred, enter: 


cnt_load -10 Set the counter to count ten events and then stop 


—(count) 
cnt_ins Count the instruction fetches 
stop_cent Stop the processor when the counter reaches 0 


In this example, you must load the counter with a negative value because the 
evicnir register represents a 1s complement of the loaded value. 


To reset the internal event counter and count the number of instruction fetches 
detected, enter: 


cnt_load 0 Reset the counter 


cnt_ins Count the number of instruction fetches detected 
You can count only one event ata time. To count any of the other events, simply 
type in the appropriate command. Table A—2 shows the correct command for 
counting each of the nine events. 


Table A—2. The Analysis Commands 
Command 
cnt_br 
cnt_call 
cnt_clock 
cnt_data 
cnt_ins 


cnt_intr 


cnt_pclk 


cnt_prog 


cnt_ret 


Menu Selection 
Branch taken 


Call taken 

CPU clock 
Data bus 
Instruction fetch 


Interrupt/trap 
taken 


Pipeline clock 


Program bus 


Return taken 


Description 
Count the number of branches detected 


Count the number of calls detected 
Count the number of CPU clock cycles 
Count the number of data cycles 

Count the number of instruction fetches 


Count the number of interrupts/traps 
detected 


Count the CPU pipeline execution clocks 


Count the number of program address 
accesses 


Count the number of returns from inter- 
rupts, traps, or subroutine calls 
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Setting breakpoints on a single program or data address 


The simplest events to detect are those that identify a single address. To define 
this type of event, follow the command with a C expression. For example, to 
set a program address breakpoint, enter: 


asys_on Turn the analysis interface on 
prog_brk_add main Set a program address breakpoint on 
function_name 

stop_prog Enable the processor to stop on the 
breakpoint condition 

run Run the program 
prog_brk_add My Function Set a new program address 
breakpoint on function_name2 

run Run to the new breakpoint 


The commands shown in bold represent the actual breakpoint commands 
used. Main and My_Function represent the addresses on which the processor 
will break. These function names can be replaced by specific address loca- 
tions. Table A-3 shows the breakpoint commands for setting single address 
breakpoints; their respective menu selections can be found in the Analysis 
Break Events dialog box. You can set breakpoints on any combination of these 
events. 


Table A-3. Breakpoint Commands for Program and Data Addresses 
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Dialog Box 
Command Selection Description 
data_brk_add address Data bus Set a data breakpoint address 
prog_brk_add address Program Set a program breakpoint address 
bus 
stop_data Data bus Stop the processor when the data 
breakpoint condition executes 
stop_prog Program Stop the processor when the pro- 
bus gram breakpoint condition executes 
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Breaking on event occurrences 


You can set conditions on various types of processor operations. To define 
these conditions or events, simply enter the command. For example, to stop 


the processor when it detects an interrupt or a call taken, enter: 


asys_on 


stop_intr 


stop_call 


Turn the analysis interface on 


Enable the processor to stop when it 
detects an interrupt 


Enable the processor to stop when it 
detects a call taken 


Table A-4 shows the commands for stopping the processor when an event oc- 
curs. You can set breakpoints on any combination of these events. 


Table A-4. Breakpoint Commands for Event Occurrences 


Command Menu Selection Description 

stop_br Branch taken Stop the processor when a branch is 
taken 

stop_call Call taken Stop the processor when a call is taken 

stop_disc Discontinuity Stop the processor with any discontinu- 
ity 

stop_emu0 EMUO drivenlow _ Stop the processor when the EMU pin 
reaches a logic low of zero 

stop_emu1 EMU1 drivenlow Stop the processor when the EMU pin 
reaches a logic low of one 

stop_intr Interrupt/trap Stop the processor when an interrupt is 

taken detected 

stop_off none Disable break events 

stop_pclk Pipeline clock Stop the processor on a pipeline clock 
(instruction fetched) 

stop_ret Return taken Stop the processor when a return from 


an interrupt, branch, or call occurs 
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Qualifying on a read or a write 


Data and program accesses can be qualified, depending on whether the 


memory cycle is a read or write: 


go function_name 


data_qual_w 
data_brk_add data_symbol 


cnt_data 


run 


Run to the beginning of the function 
function_name 


Look only at writes 
Set a data address breakpoint 


Enable the processor to count any 
writes to the specified data access 


Count the number of any writes to 
data_symbol 


This example sets a data address breakpoint that counts only when a write is 
detected. Table A-5 shows the qualifier commands for data and program 
break events. You can use only one of these commands at a time. 


Table A—5. Read and Write Qualifying Commands for Data and Program Accesses 


Command Menu Selection 
data_qual_r Data bus: Read 
data_qual_rw Data bus: Access 
data_qual_w Data bus: Write 


prog_qual_iaq Program bus: Fetch 


prog_qual_r Program bus: Read 
prog_qual_rw Program bus: Access 


Description 
Look only at data reads 


Look at both data reads and writes 
Look only at data writes 

Program instruction acquisition 
Look only at data reads 


Look at both data reads and writes 


prog_qual_w Program bus: Write 
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Look only at data writes 
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Resetting the analysis interface 


Whenever you begin a new analysis session, you may want to define new pa- 
rameters or qualifier expressions. You can do this without manually 
deselecting each defined condition. Just enter the ASYS_ RESET command. 
To reset the analysis interface, type: 

asys_reset 


Cc OTT 
Note: 


To clear conditions or qualifier expressions previously defined via the Analy- 
sis menu, you must open the Analysis Count Events and Analysis Break 
Events dialog boxes and deselect each defined condition. 


A.2 Using the Analysis Registers 


By manipulating the analysis registers, you can customize commands for 
more complex instructions that do not exist on the Break or Count dialog 
boxes. Use the alias and evaluate commands to create your own commands. 
The basic syntax for creating customized analysis commands is: 


alias command_name, eval register name = code” 


For example, to create a new command for turning on the analysis interface, 
enter: 


alias analysis_on, "eval anaenbl = 1” 
To create a new command for counting branches detected, enter: 
alias cb, "e evtselt = 12” 


To create your own analysis commands, you must familiarize yourself with the 
thirteen analysis registers and how they work. The following subsections dis- 
cuss the analysis registers briefly. (The registers are in alphabetical order.) 
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anaenbl (Enable Analysis) 


You can enable and disable the analysis module by using the anaenbl register. 
Set the bit to 1 to enable or to 0 to disable. 


Bit Number Description 

enable analysis module 
reserved (set to 0) 
reserved (set to 0) 
enable external counter 
enable EMUO output 
enable EMU1 output 
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When you disable analysis, all registers except anaenbl retain their previous 
state. 


anastat (Analysis Status) 


The anastat register records the occurrence of enabled events. The status bits 
are defined below: 


Bit Number Definition 
call taken 
return from interrupt/trap/subroutine 
interrupt/trap taken 
branch taken 
pipeline clock 
program address 
data address 
discontinuity 
event counter passed zero 
EMUO detected low 
0 EMU1 detected low 


- OAN OA HRWN + CO 


Run commands will not interfere with the status bits, because they are cleared 
before command execution. 


Using the Analysis Registers 


datbrkp (Data Breakpoint Address) 


You can specify a breakpoint address for each of the major buses in the ’C5x 
path. When a valid bus cycle occurs and the bus value matches the breakpoint 
address, then a breakpoint condition can occur. 


datqual (Data Breakpoint Qualifier) 


The data breakpoint register has four qualifier bits. The qualifier definitions are 
shown below. 


Qualifier Code Definition 
0 read 

1 write 

2 reserved 
3 read/write 


evicntr (Event Counter) 


This register represents a true value in the ’C5x analysis module, which 
provides a 16-bit decrementing event counter. For convenience, the pseudo- 
register, EVT_cntr, provides a 1s complement of the evtcnir value. 


You can use the event counter in one of two ways: 


[_] Count the number of events detected. 
[__] Stop after n events have occurred. 


To count the number of events detected, load the counter with its maximum 
value —1, or OxXFFFF. The following example loads the counter and counts the 


instructions. 
cnt_load 0 Reset the counter 
cent_ins Count the number of instruction fetches detected 


The EVT_cnitr register will display the number of events detected after reach- 
ing a stop condition. 
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Using the Analysis Registers 


To stop after a certain number of events, load the counter with the number of 
events you want to occur before setting a breakpoint. The following example 
counts ten events and then stops. 


cnt_load -10 Set the counter to count ten events and then stop 

—(count) 
cnt_ins Count instruction fetches 
stop_cnt Stop the processor when the counter reaches 0 


If a software breakpoint halts the processor before the counter reaches zero, 
then the CNT_valu (displayed in the WATCH window) will contain the number 
of events remaining. 


ae, 
Note: 


When CPU clock cycles are counted, the event counter includes startup and 


latency cycles. 
| 


evtselt (Select the Event for Counting) 


The ’C5x can count ten types of events; however, only one event can be 
counted at a time. The count select codes are defined below. 


Select Code Definition 

0 CPU clocks 

1-7 not used 

8 instruction fetched 

9 call taken 

10 return from interrupt/trap/subroutine 
11 interrupt/trap taken 

12 branch taken 

13 pipeline clocks 

14 program address breakpoints 
15 data address breakpoints 


hbpenbl (Select Hardware Breakpoints) 


Using the Analysis Registers 


By setting the appropriate enable bit to 1 in the hbpenbl register, the ’C5x can 
break on multiple events. Setting the bit to 0 disables the breakpoint and clears 
the register. The breakpoint enable bits are defined below. 


Bit Number 
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oO 


pgabrkp (Program Address Breakpoint) 


Definition 

call taken 

return from interrupt/trap/subroutine 
interrupt/trap taken 
branch taken 

pipe clock 

program address 
data address 
discontinuity 

counter passing zero 
EMUO detected low 
EMU1 detected low 


You can specify a breakpoint address for each of the major buses in the ’C5x 
path. When a valid bus cycle occurs and the bus value matches the breakpoint 
address, then a breakpoint condition can occur. 


pgaqual (Program Breakpoint Qualifier) 


The data breakpoint register has four qualifier bits. The qualifier definitions are 


shown below. 


Qualifier Code 
0 


{ 
2 
3 


Definition 

read 

write 

program instruction acquisition 
read/write 
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Using the Analysis Registers 


ptrace0/ptrace1/ptrace2 (Discontinuity Trace Samples 0-2) 


Example A-1. 


A program discontinuity occurs when the program addresses fetched by the 
processor become nonsequential as a result of branches, interrupts, and simi- 
lar events. The ’C5x provides three levels of discontinuity trace to aid in pro- 
gram flow analysis: 


Register 
ptraceO 
ptrace1 
ptrace2 


Name 

discontinuity trace sample 0 
discontinuity trace sample 1 
discontinuity trace sample 2 


Program Discontinuity 
Address 


300A 
300B 
300C 
300E 
300F 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 
301 


QU roman OB WBNHEHR OO 


Code 
nop 
nop 
b dcon2 
nop 
nop 
nop 
dcon2: nop 


b dconl 


dconl: nop 


nop 


Description 

traces the current code segment 
traces the previous code segment 
traces the oldest code segment 


Comment 


discontinuity occurs 
branch from 


branch to 


discontinuity occurs 
branch from 


branch to 


Stepping through the code starting at address 0x300A with ptrace0/1/2 initial- 
ized to zero, the trace buffer will show the following: 


[(_} Following the first branch (b dcon2), the trace contains the following val- 
ues: 


P 
P 
P 


RAC] 


E2 


RAC] 


Ei 1 


RAC] 


EO 


0x0000 


0x300E _ /ast instruction fetched before the branch 
0x3011 branch to address (dcon2) 


[(_} Following the second branch (b dcon1), the trace contains the following 


values: 


IP 
P. 
iP 


RAC] 


E2 


RACI 


E1 


RAC] 


EO 


0x3011 discontinuity from the oldest code segment 
0x3017 discontinuity from the previous code segment 
0x301A current code segment 
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Note: All page numbers preceded by the word EMU refer to the TMS320C5x Emulator Installation 
Guide; page numbers preceded by S/M refer to the TMS320C5x Simulator Getting Started Guide, and 
page numbers preceded by EVM refer to the TMS320C5x EVM Installation Guide. All other references 


refer to this user’s guide. 


!command 2-13 to 2-14, 13-13 

2? command 8-3, 13-12 
display formats 3-25, 8-21, 13-12 
examining register contents 3-16, 8-12 
modifying PC 7-12 
side effects 8-5 

$$EMU$$ 5-19 

$$EVM$$ 5-19 

$$SIM$$ 5-19 

@command 2-19, 13-13 


absolute addresses 8-7, 9-3 
access qualification 
bus accesses 
hardware breakpoints 11-10 to 11-12 
active window 4-19 to 4-21 
breakpoints 9-3 
current field 3-6, 4-18 
customizing its appearance 10-4 
default appearance 4-19 
definition E-1 
effects on command entry 5-3 
identifying 3-6, 4-19 
moving 3-9, 4-24 to 4-26, 13-38 
selecting 3-5 to 3-6, 4-20 to 4-21, 13-62 
function key method 3-6, 4-20, 13-69 
mouse method 3-6, 4-20 
WIN command _ 3-5, 3-6, 4-20, 13-62 
sizing 3-7, 4-21 to 4-23, 13-53 to 13-54 
zooming 3-8, 4-23 to 4-24, 13-63 


ADDR command 7-5, 7-9, 13-14 
effect on DISASSEMBLY window 4-7 
effect on FILE window 4-8 
finding current PC 7-12 


address qualification 
bus accesses 
hardware breakpoints 11-10 to 11-12 


addresses 
absolute addresses 8-7, 9-3 
accessible locations 6-1, 6-2 
contents of (indirection) 8-9, 8-17 
data-memory notation 3-5, 4-13 to 4-15 
hexadecimal notation 8-7 
I/O address space 
emulator 1-4 to 1-5, 1-12, 2-4 to 2-5, 2-12 
EVM 4,5, 10to 11 
simulator 6-11 to 6-15 
in MEMORY window _ 3-5, 4-12, 8-7 
invalid memory 6-3 
nonexistent memory locations 6-2 
pointers in DISP window 3-22 
program-memory notation 3-5, 4-13 to 4-15 
protected areas 6-3, 6-7 
symbolic addresses 8-7 
undefined areas 6-3, 6-7 


aggregate types 
definition E-1 
displaying 3-21, 4-16, 8-13 to 8-15 
ALIAS command 3-28, 5-21 to 5-23, 13-15 
See also aliasing 
PDM version 2-15 to 2-16 
supplying parameters 5-22 


Index-1 


Index 


aliasing 2-15 to 2-16, 5-21 to 5-23 
ALIAS command 3-28, 5-21 to 5-23, 13-15 
PDM version 2-15 to 2-16 
definition E-1 
deleting aliases 5-23 
finding alias definitions 5-22 
limitations 5-23 
listing aliases 5-22 
redefining an alias 5-23 


Analysis Break Events dialog box 5-13, 11-8, 
11-10 


Analysis Count Events dialog box 11-6, 11-7 


analysis interface 11-1 to 11-16 

commands 13-11, A-1 to A-14 

counting events 11-2, 11-6 
bus accesses 11-2, 11-9 to 11-10 
calls taken 11-2 
CPU clock cycles 11-2 
dialog box 11-6 
EMU pins 11-11 to 11-12 
event comparators 11-9 to 11-10 
instruction fetches 11-2 
interrupts taken 11-2 
returns taken 11-2 

defining conditions 11-6 to 11-12 

description 1-5, 11-2 to 11-3 

dialog boxes 
Analysis Break Events 11-8, 11-10 
Analysis Count Events 11-6, 11-7 

disabling 11-5 

discontinuity 11-3, 11-14 to 11-16 
stack 11-14 to 11-16 

EMU pins 11-11 to 11-12 
description 11-3 
restrictions 11-11 

enabling 11-5 

global breakpoints 11-12 

hardware breakpoints 11-2, 11-8 to 11-12 
breaking on branches taken 11-8 
breaking on bus accesses 11-9 to 11-10 
breaking on calls taken 11-8 
breaking on discontinuity 11-8 
breaking on EMU pins 11-8 
breaking on event comparators 11-9 to 11-10 
breaking on instruction fetches 11-8 
breaking on interrupts taken 11-8 
breaking on pipeline clocks 11-8 
breaking on returns 11-8 
breaking on the internal event counter 11-8 
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analysis breakpoints, hardware breakpoints (continued) 
breaking on traps taken 11-8 
bus accesses 11-2, 11-8 to 11-12 
calls taken 11-2 
EMU pins 11-2, 11-3, 11-11 to 11-12 
event counter passing zero 11-8 
instruction fetches 11-2 
interrupts taken 11-2 
returns taken 11-2 
simple events 11-8 
internal counter 11-6 
key features 1-5, 11-2 to 11-3 
menu selections 11-5 
EMU selection 11-11 
PC discontinuity stack. See analysis interface, 
discontinuity 
process 11-4 
running programs 11-13 
View window 11-14 
viewing analysis data 11-14 to 11-16 
interpreting the discontinuity stack 11-14 to 
11-16 
interpreting the event counters 11-16 
interpreting the PTO field 11-14 to 11-16 
interpreting the PT1 field 11-14 to 11-16 
interpreting the PT2 field 11-14 to 11-16 
interpreting the STAT field 11-14 
sample code and discontinuity stack 11-15 
Analysis menu selections 11-5, 13-11 
Break selection 11-6, 11-8 
Count selection 11-7 
EMU selection 11-11 
View selection 11-14 to 11-16 
analysis module. See analysis interface 
ANSI C_ 1-10 
definition E-1 
ARO register 8-12 
area names (for customizing the display) 
code-display windows 10-5 
COMMAND window 10-4 
common display areas 10-3 
data-display windows 10-6 
menus 10-7 
summary of valid names 10-3 to 10-7 
window borders 10-4 
arithmetic operators 14-2 
arrays 
displaying/modifying contents 8-14 
format in DISP window 3-23, 8-14, 13-22 
member operators 14-2 


arrow keys = S/M2-7 
COMMAND window — 5-3 
editing 8-4 
moving a window 3-9, 4-25, 13-69 
moving to adjacent menus 5-9 
scrolling 3-10, 4-27, 13-70 
sizing a window 3-7, 4-23, 13-69 
—as shelloption 1-13, 12-2 
ASMcommand_ 3-13, 7-3, 13-15 
menu selection 7-3, 13-11 
assembler 1-11, 1-12; EMU 1-3, 2-3; EVM3; 
SIM 1-3, 2-2 
assembly language code 
displaying 4-2 to 4-30, 7-4 
modifying 7-5 to 7-6 
assembly mode 3-12 to 3-13, 4-3, 7-2 
ASM command 3-13, 7-3, 13-15 
definition E-1 
selection 7-3 
assignment operators 8-5, 14-3 
attributes 10-2 
auto mode 3-12 to 3-13, 4-2 to 4-3, 7-2 
C command 3-13, 7-3, 13-18 
definition E-1 
selection 7-3 


autoexec.bat file EMU 2-9 to 2-12; EVM8 to 11; 


SIM 1-5 to 1-7 

definition E-1 

invoking EMU 2-10; EVM9; SIM 1-6 

sample EMU 2-10; EVM8; SIM 1-5 
auxiliary registers 8-12 


—b debugger option 1-17 to 1-18 
effect on window positions 4-25 
effect on window sizes 4-22 
with D-OPTIONS environment variable 
emulator 1-12, 2-12 
EVM 10 
simulator 1-7, 2-5 
BA command 9-3, 13-16 
menu selection 13-10 
background 10-3 
batch files 5-17 
autoexec.bat EMU 2-9 to 2-12; EVM8 to 11; 
SIM 1-5 to 1-7 
sample EMU 2-10 


Index 


batch files (continued) 


board.cfg C-1 to C-5; EMU 1-3 
sample C-2, C-4 
board.dat C-1 to C-5; EMU 1-3 
config.sys EMU 1-9 to 1-14 
sample EMU 1-10 
controlling command execution 2-10 to 2-14, 
5-18 to 5-21 
conditionalcommands 2-10 to 2-14, 5-18 to 
5-19, 13-5, 13-29 to 13-63 
looping commands 2-11 to 2-12, 5-20 to 
5-21, 13-5, 13-31, 13-32 
.cshre =96SIM 2-4 to 2-5 
definition E-1 
displaying 7-9 
displaying text when executing 2-12, 5-18, 
13-5, 13-24 
echoing messages 2-12, 5-18, 13-5, 13-24 
emuinit.cmd 6-10; EMU 1-3, 2-3 
emurst EMU 1-3, 1-13, 2-3, 2-12 
evminit.cmd EVM3 
evmrst EVM3, 11 
execution 13-58 
halting execution 5-17 
init.clr 10-9, B-1 
emulator 1-3, 2-3 
EVM 3 
simulator 1-3, 2-2 
init.cmd 6-2, B-1 
definition E-4 
initppdm 1-15 
initdb.bat EMU 2-9 to 2-12; EVM8 to 11; 
SIM 1-5 to 1-7 
sample EMU 2-10 
initdb.cmd EMU 1-9 to 1-14 
sample EMU 1-10 
initialization 6-2, 6-3, B-1 
emuinit.cmd EMU 1-3, 2-3 
evminit.cmd EVM3 
init.cmd B-1 
initpdm 1-15 
siminit.cmd 6-2 
PC systems S/M1-3 
SPARC systems S/M2-2 
invoking 
autoexec.bat EMU 2-10; EVM 9; SIM 1-6 
config.sys EMU 1-10 
.cshte = SIM2-5 
initdb.bat EMU 2-10; EVM 9; SIM 1-6 
initdb.cmd EMU 1-10 
mem.map 6-10 
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batch files (continued) break event 
memory maps_ 6-10 definition E-1 
mono.clr 10-9 breakpoints (hardware) 11-8 to 11-12 
emulator 1-3, 2-3 breaking on bus accesses 11-9 to 11-10 
EVM 3 breaking on event comparators 11-9 to 11-10 
simulator 1-3, 2-2 definition E-1 
screen sizes SIM 1-3, 2-2 global 11-11 to 11-12 
siminit.cmd SIM 1-3, 2-2 breakpoints (software) 9-1 to 9-5 
startup.cmd EMU 1-13 active window 3-6 
TAKE command 5-17, 6-10, 13-58 adding 9-2 to 9-3, 13-16 
PDM version 2-9 command method 9-3 
—bb debugger option 3-3 function key method 9-3, 13-70 
See also —b debugger option mouse method 9-3 
BD command 9-4, 13-16 benchmarking with RUNB_ 3-16, 7-19 
menu selection 13-10 clearing 3-16, 9-4, 13-16, 13-17 


command method 9-4 
function key method 9-4, 13-70 
mouse method 9-4 


benchmarking 3-16, 7-13, 7-19 
constraints 7-19 


definition E-1 
roe commands 13-6 
bitwise operators 14-3 BA command 82. 1846 
BLcommand 9-5, 13-16 BD command 9-4, 13-16 
menu selection 13-10 BL command 9-5, 13-16 
blanks 10-3 BRcommand 3-16, 9-4, 13-17 
board configuration menu selections 13-10 
creating the file C-2 to C-5 definition E-1 
naming an alternate file 1-17, 1-18, C-5 listing set breakpoints 9-5, 13-16 
specifying the file C-5 restrictions 9-2 
translating the file C-5; EMU 1-3 setting 3-15, 3-16, 9-2 to 9-3 
board.cfg file C-1 to C-5; EMU 1-3 command method 9-3 


function key method 9-3, 13-70 


device names C-3 bneowieiicd Os 


device types 


BYPASS## C-4 bus accesses 

SPL C-3 See also analysis interface 

TI320C5x C-3 counting events 11-9 to 11-10 
sample C-2, C-4 hardware breakpoints 11-9 to 11-10 
translating C-5; EMU 1-3 bus protocol EMU 3-3 
types of entries C-3 to C-5 BYPASS## device type C-4 


board.dat file C-1 to C-5; EMU 1-3 


default C-1 
errormessages EMU 1-17 


BORDER command 10-8, 13-17 


menu selection 13-11 Ccommand 3-13, 7-3, 13-18 
borders menu selection 7-3, 13-11 
colors 10-4 C expressions 8-5, 14-1 to 14-6 
styles 10-8 See also expressions 
BRcommand 3-16, 9-4, 13-17 C language, definition [E-2 
menu selection 13-10 C source 
branches taken 11-8 displaying 3-11, 4-2 to 4-3, 4-4, 7-4, 13-26 
BREAK command 2-11 to 2-12, 13-31 managing memory data 8-9 
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cdxhll directory 
emulator 1-9, 1-11, 2-9, 2-11 
EVM 7,9 

cable pod EMU3-4 to 3-5 


CALLS command 4-9, 4-10, 7-9, 13-18 
effect on debugging modes 4-4 


calls taken 11-8 
See also analysis interface 


CALLS window 3-11, 4-5, 4-9 to 4-10, 7-2, 7-9 
closing 4-10, 4-29, 13-69 
definition E-2 
opening 4-10, 13-18 
casting 3-24 to 3-25, 8-9, 14-4 
definition E-2 
changing the debugger display (font) S/M2-8 
CHDIR (CD) command 3-21, 5-25, 7-11, 13-18 
children 
See also DISP window, children 
definition E-2 
clearing the display area 3-21, 5-5, 13-19 
“click and type” editing 3-26, 4-28, 8-4 to 8-5 
clicking 
definition E-2 
CLK pseudoregister 3-16, 7-19 
definition E-2 
closing 
awindow 4-29 
CALLS window 4-10, 13-69 
debugger 1-20, 3-28, 13-45 
dialog boxes 5-15 to 5-16 
DISP window 3-23, 8-15, 13-69 
log files 2-10, 5-6, 13-23 
MEMORY window 4-15 
PDM 1-20, 13-45 
WATCH window 3-20, 8-17, 13-63 
CLS command 3-21, 5-5, 13-19 
CNEXT command 7-15, 13-19 
code 
debugging 1-21 
code-display windows 4-5, 7-2 
CALLS window 3-11, 4-5, 4-9 to 4-10, 7-2, 7-9 
definition E-2 
DISASSEMBLY window _ 3-5, 4-5, 4-7, 7-2, 7-4 
effect of debugging modes 7-2 
FILE window 4-5, 4-8, 7-2, 7-4, 7-8 


Index 


code-execution (run) commands. See run com- 
mands 


COFF 
definition E-2 
loading 6-3 


COLOR command 10-2, 13-19 to 13-20 
color.clr 10-9 


colors 10-2 to 10-7 
areanames 10-3 to 10-7 


mapping with X Windows S/M 2-8 


comma operator 14-4 


command history 5-5 
function key summary 13-67 
PDM version 2-13 to 2-14, 13-13 


commandline 4-6, 5-2 
changing the prompt 10-12, 13-43 
cursor 4-18 
customizing its appearance 10-4, 10-12 
definition E-2 
editing 5-3 
function key summary 13-67 


COMMAND window 4-5, 4-6, 5-2 

colors 10-4 

commandline 3-4, 4-6, 5-2 
editing keys 13-67 

customizing 10-4 

definition E-2 

display area 3-4, 4-6, 5-2 
clearing 13-19 

recording information from the display area 5-6 
to 5-8, 13-5, 13-23 


commands 
alphabetical summary 13-12 to 13-63 
analysis commands” 13-11, A-1 to A-14 
See also Analysis menu selections 
batch files 5-17 
controlling command execution 
conditional commands 5-18 to 5-19, 13-5, 
13-30 
looping commands 5-20 to 5-21, 13-5, 13-32 
breakpoint commands 9-1 to 9-5, 13-6 
See also breakpoints, commands 
code-execution (run) commands 7-12, 13-7 
See also run commands 
command line 5-2 to 5-6 
command strings 2-15 to 2-16, 5-21 to 5-23 
conditional commands 2-10 to 2-14, 5-18, 
13-29 to 13-63 
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commands (continued) 
controlling command execution 
conditional commands 2-10 to 2-14, 13-29 to 
13-63 
looping commands 2-11 to 2-12, 13-31 
customizing 2-15 to 2-16, 5-21 to 5-23 
data-management commands 8-2 to 8-22, 13-4 
See also data-management commands 
entering and using 5-1 to 5-25 
file-display commands _ 7-4 to 7-9, 13-6 
See also file/load commands 
load commands 7-10, 13-6 
See also load/file commands 
looping commands 2-11 to 2-12, 5-20, 13-31, 
13-32 
memory commands 6-5 to 6-19 
See also memory, commands 
memory-map commands’ 13-7 
See also memory, mapping, commands 
menu selections 5-7 
mode commands 7-2 to 7-3, 13-4 
See also debugging modes, commands 
PDM commands 13-3 
profiling commands 13-8 
See also profiling, commands 
run commands. See run commands 
screen-customization commands 10-1 to 10-12, 
13-6 
See also screen-customization commands 
system commands 2-16, 5-24 to 5-26, 13-5 
See also system commands 
window commands’ 13-4 
See also windows, commands 


compiler 1-10, 1-12; EMU 1-3, 2-3; EVM3; 
SIM 1-3, 2-2 
key characteristics 1-10 

composer utility C-5; EMU 1-3 

conditional commands 2-10 to 2-14, 5-18 to 5-19, 
13-29 to 13-63 


config.sys file EMU 1-9 to 1-14 


invoking EMU 1-10 

sample EMU1-10 

setting the IOPL option EMU 1-13 
configuration 

multiprocessor EMU 3-9 
connector 

target system to emulator EMU 1-7, 2-7, 3-1 to 

3-14 
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constraints 
benchmarking 7-19 
CLK 7-19 


CONTINUE command 2-11 to 2-12, 13-31 


control bits 
FO 13-34 
SPC 13-34 
TDM 13-34 
TSPC 13-34 
counting events 
See also analysis interface 
bus accesses 11-9 to 11-10 
event comparators 11-9 to 11-10 
CPU clock cycles. See analysis interface 
CPU window 4-5, 4-15, 8-2, 8-12 to 8-13 
colors 10-6 
customizing 10-6 


definition E-2 
editing registers 8-4 
.cshrc file S/M2-4 to 2-5 


invoking S/IM2-5 
CSTEP command 3-18, 7-15, 13-20 
current directory 
changing 5-25, 7-11, 13-18 
current field 
cursor 4-18 
dialog box 5-4 
editing 8-4 to 8-5 
current PC 3-4, 4-7 
finding 7-12 
selecting 7-12 
cursors 4-18 
command-line cursor 4-18 
definition E-2 
current-field cursor 4-18 
definition E-2 
definition E-2 
mouse cursor 4-18 
definition E-5 
customizing the display 10-1 to 10-12 
changing the font S/M2-8 
changing the prompt 10-12 
colors 10-2 to 10-7 
changing 5-25, 7-11, 13-18 
init.clr file 
emulator 1-3, 2-3 
EVM 3 
simulator 1-3, 2-2 
loading acustom display 10-10, 13-50 


customizing the display (continued) 
mono.clr file 
emulator 1-3, 2-3 
EVM 3 
simulator 1-3, 2-2 
saving a custom display 10-9, 13-56 
screen sizes SI/M 1-3, 2-2 
window border styles 10-8 


—d debugger option 1-17, 1-18 
D_DIR environment variable 1-15, 5-17, 10-10, 
13-50 
emulator 1-11, 2-11 
EVM 9 
simulator 1-7, 2-4 
definition E-3 
effects on debugger invocation B-1 
D_OPTIONS environment variable 1-17 to 1-20 
emulator 1-12, 2-12 
EVM 10 
simulator 1-7, 2-4 
definition E-3 
effects on debugger invocation B-1 
ignoring 1-20 
D_SRC environment variable 1-14, 1-16, 7-11 
emulator 1-11, 2-11 
EVM 10 
simulator 1-7, 2-4 
definition E-3 
effects on debugger invocation B-1 
DASM command 7-5, 13-21 
effect on debugging modes 4-4 
effect on DISASSEMBLY window 4-7 
finding currentPC 7-12 


data 
in MEMORY window 4-12 


data formats 8-19 
datatypes 8-20 


datamemory 4-13 to 4-15 
adding to memory map_ 6-5, 13-32 to 13-33 
deleting from memory map 6-9, 13-35 
filling 8-11, 13-26 
saving 8-10, 13-39 

datatypes 8-20 
See also display formats 


Index 


data-display windows 4-5, 8-2 


colors 10-6 

CPU window 4-5, 4-15, 8-2, 8-12 

definition E-3 

DISP window 3-21, 4-5, 4-16, 8-2, 8-13 to 8-15 

MEMORY window _ 3-5, 4-5, 4-12 to 4-15, 8-2, 
8-6 to 8-11 

WATCH window 3-17, 4-5, 4-17, 8-2, 8-16 to 
8-17 


data-management commands 3-22, 8-2, 13-4 


2?command 7-12, 8-3, 8-12, 13-12 

controlling data format 3-24 to 3-25, 8-9 

data-format control 8-19 to 8-22 

DISP command 3-21 to 3-23, 8-14, 13-22 to 
13-25 

EVAL command 7-12, 8-3, 13-25 
PDM version 2-21, 13-25 

FlLL command 8-11, 13-26 

MEM command 3-5, 4-13, 4-14, 4-15, 8-7, 
13-35 to 13-36 

MS command 8-10, 13-39 

SETF command 3-24 to 3-25, 8-19 to 8-22, 
13-52 to 13-53 

side effects 8-5 

WA command 3-17, 5-11 to 5-12, 8-12, 8-16, 
13-61 to 13-62 

WD command 3-19, 8-17, 13-62 

WHATIS command 3-20, 8-2, 13-62 

WR command 3-20, 8-17, 13-63 


debugger 


analysis interface 
description 1-5 
key features 1-5 
changing the displayed font S/M2-8 
definition E-3 
description 1-2 to 1-4 
display 3-4 
basic 1-2 
environment setup 
emulator 
DOS EMU 2-9 to 2-12 
OS/2 EMU 1-9 to 1-14 
EVM 8to11 
simulator 
PC systems SIM 1-5 to 1-7 
SPARC systems SIM 2-4 to 2-5 
exiting 1-20, 13-45 
installation EVM7 
describing the target system C-1 to C-5; 
EMU 1-15 
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debugger, installation (continued) 
emulator 
DOS EMU 2-1 to 2-15 
OS/2 EMU 1-1 to 1-18 
EVM EVM 1 to 13 
error messages EMU 1-17, 2-14; EVM 13 
simulator 1-3, 2-2 
verifying EMU 1-16, 2-13; EVM 12; 
SIM 1-8, 2-6 
simulator 
PC systems SIM 1-1 to 2-9 
SPARC systems SI/M2-1 to 2-8 
invocation 3-3, 13-55 
options 1-17 to 1-20 
standalone 1-14 
task ordering B-1 
under PDM control 1-15 to 1-16 
key features 1-3 to 1-4 
messages D-1 to D-26 
pausing 13-40 
using the X Window System SIM 2-7 to 2-8 
using with MS-Windows EMU 2-9, 2-15; 
EVM7,13; SIM 1-4, 2-9 


debugging modes 3-12 to 3-13, 4-2 to 4-4, 7-2 to 
7-3 
assembly mode 3-12 to 3-13, 4-3, 7-2 
auto mode 3-12 to 3-13, 4-2 to 4-3, 7-2 
commands 13-4 
ASM command 3-13, 7-3, 13-15 
Ccommand 3-13, 7-3, 13-18 
menu selections 13-11 
MIX command 3-13, 7-3, 13-37 
default mode 4-2, 7-2 
menu selections 3-12, 7-3 
mixed mode 3-12 to 3-13, 4-4, 7-2 
restrictions 4-4 
selection 3-12 to 3-13 
command method 3-13, 7-3 
function key method 7-3, 13-68 
mouse method 3-12, 7-3 


decrement operator 14-3 


default 
data formats 8-19 
debugging mode 4-2, 7-2 
display 3-4, 4-2, 7-2, 10-11 
group 2-4, 13-51 
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default (continued) 
I/O address space 
emulator 
DOS EMU 2-4 to 2-5 
OS/2 EMU 1-4 to 1-5 
EVM 4,5 
memory map 3-27, 6-3 
emulator 
DOS EMU 2-3 
OS/2. EMU 1-3 
EVM 3 
simulator 
PC systems SIM 1-3 
SPARC systems SIM 2-2 
screen configuration file 10-9; EVM3 
color displays EMU 1-3, 2-3; EVM 3; 
SIM 1-3, 2-2 
screen sizes SIM 1-3, 2-2 
switch settings EVM4 
emulator 
DOS EMU 2-4 to 2-5 
OS/2 EMU 1-4 to 1-5 
defining areas for profiling 12-5 to 12-12 
disabling areas 12-7 to 12-9 
enabling areas 12-10 
marking areas 12-5 to 12-7 
restrictions 12-12 to 12-17 
unmarking areas 12-11 to 12-12 
device name C-3 
device types 
BYPASS## C-4 
debugger devices C-3 
SPL C-3 
TI320C5x C-3 
dgroup 2-4 
dialog boxes 5-11 to 5-16 
analysis interface 11-6, 11-7, 11-8, 11-10 
closing 5-12, 5-15 to 5-16 
function key method 5-16 
mouse method 5-15 
complex 5-12 
components of 5-13 
effect on entering other commands 5-4 
enabling parameters 11-8 
entering parameters 5-11 to 5-12 
modifying textin 5-12 
parameters 
enabling 5-13 
function key method 5-14 to 5-15 
mouse method 5-14 
predefined 5-12, 5-13 


dialog boxes (continued) 
qualifiers 
enabling 5-14 
function key method 5-14 to 5-15 
mouse method 5-14 
predefined 5-12, 5-13 
selecting parameters 5-12 
selecting qualifiers 5-12 
using 5-11 to 5-16 


DIR command 3-21, 5-25, 13-21 


directories 
c5xhil directory EVM7,9; SIM 1-4 
emulator 
DOS EMU 2-9, 2-11 
OS/2 EMU 1-9, 1-11 
changing current directory 5-25, 13-18 
for auxiliary files EVM9 
simulator 
PC systems SIM 1-7 
SPARC systems SIM 2-4 
emulator 
DOS EMU 2-11 
OS/2 EMU 1-11 
for debugger software EVM/7,9 
emulator 
DOS EMU 2-9, 2-11 
OS/2 EMU 1-9, 1-11 
simulator 
PC systems SIM 1-6 
SPARC systems SIM 2-3 
identifying additional source directories 13-59; 
EVM 10 
emulator 
DOS EMU 2-11 
OS/2 EMU 1-11 
USE command 13-59 
simulator 
PC systems SIM 1-7 
SPARC systems SIM 2-4 
identifying current directory 7-11 
listing contents of current directory 5-25, 13-21 
relative pathnames 5-25, 13-18 
search algorithm 5-17, 7-11, B-1 
sim5x directory 
PC systems SIM 1-7 
SPARC systems SIM 2-3, 2-4 


disabling areas 12-7 to 12-9 


disassembly 
definition E-3 


Index 


DISASSEMBLY window _ 3-5, 4-5, 4-7, 7-2, 7-4 
colors 10-5 
customizing 10-5 
definition E-3 
modifying display 13-21 


discontinuity 11-8 
definition E-3 
stack 
interpreting 11-14 to 11-16 


DISP command 3-21, 4-16, 8-14, 13-22 to 13-25 
display formats 3-25, 8-21, 13-22 
effect on debugging modes 4-4 


DISP window 3-21, 4-5, 4-16, 8-2, 8-13 to 8-15 
children 3-22, 8-14 
closing 3-23 
definition E-2 
closing 3-23, 4-29 to 4-30, 8-15, 13-69 
colors 10-6 
customizing 10-6 
definition E-3 
editing elements 8-4 
effects of LOAD command 8-15 
effects of SLOAD command 8-15 
identifying arrays, structures, pointers 13-22 
opening 8-14 
opening another DISP window 8-15 
DISP command 8-14 
function key method 3-23, 8-15, 13-70 
mouse method 3-22, 8-15 


display area 4-6, 5-2 
clearing 3-21, 5-5, 13-19 
definition E-3 
recording information from 2-10, 5-6 to 5-8, 
13-5, 13-23 


display formats 3-24 to 3-25, 8-19 to 8-22 

2? command 3-25, 8-21, 13-12 

casting 3-24 

datatypes 8-20 

DISP command 3-24, 3-25, 8-21, 13-22 

enumerated types 4-16 

EVAL command 2-21, 13-26 

floating-point values 4-16 

integers 4-16 

MEM command 3-25, 8-21, 13-36 

pointers 4-16 

resetting types 8-20 

SETF command 3-24 to 3-25, 8-19 to 8-22, 
13-52 to 13-53 

WA command 3-24 to 3-25, 8-21, 13-61 
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display requirements EVM2 
emulator 
DOS EMU 2-2 
OS/2 EMU 1-2 
simulator 
PC systems SIM 1-2 
SPARC systems SIM 2-2 


displaying 
assembly language code 7-4 
batch files 7-9 
Ccode 7-8 to 7-9 
data in nondefault formats 8-19 to 8-22 
source programs 7-4 to 7-9 
text files 7-9 
text when executing a batch file 5-18, 13-5, 
13-24 


DLOG command _ 5-6 to 5-8, 13-5, 13-23 
ending recording session 2-10, 5-6 
PDM version 2-10 
starting recording session 2-10, 5-6 


DOS 
See also MS-DOS 
display requirements EMU 2-2 
error messages 
installation EMU 2-14 
graphics card requirements EMU 2-2 
hardware requirements EMU 2-2 
host system EMU 2-2 
memory requirements EMU 2-2 
mouse requirements EMU 2-2 
Operating system EMU2-3 
power requirements EMU 2-2 
setting up debugger environment EMU 2-9 to 
2-12; EVM8to 11; SIM 1-5 to 1-7 
software requirements EMU 2-3 
targetsystem EMU 2-2 
using MS-Windows EMU 2-9, 2-15 


dragging 
definition E-3 


DRR register 6-13, 13-34 


dspcl shell 1-13 
definition E-3 


DXR register 6-13, 13-34 
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Ecommand 13-25 
See also EVAL command 
ECHO command 5-18, 13-5, 13-24 
PDM version 2-12 
“edit” key (F9) 4-28, 8-5, 13-70 
See also F9 key 
editing 
“click and type” method 3-26, 4-28, 8-4 to 8-5 
commandline 5-3, 13-67 
data values 8-4, 13-70 
dialog boxes 5-11 to 5-16 
disassembly 7-5 to 7-9, 13-40 to 13-63 
expression side effects 8-5 
FILE, DISASSEMBLY, CALLS 4-28 
function key method 3-26, 8-4 to 8-5, 13-70 
MEMORY, CPU, DISP, WATCH 4-28 
mouse method 8-4 
overwrite method 8-4 to 8-5 
window contents 4-28 
EGA 
definition E-3 
EISA 
definition E-3 
ELIF command 2-10 to 2-14, 13-24, 13-29 to 
13-63 
ELSE command _ 5-18 to 5-19, 13-5, 13-24 
See also |F/ELSE/ENDIF commands 
debugger version 13-30 
PDM version 2-10 to 2-14, 13-29 to 13-63 
$$EMU$$ constant 5-19 
EMU pins 11-8, 11-11 to 11-12 
description 11-3 
external counter 11-11 to 11-12 
restrictions 11-11 
emu5dx command 1-14, 1-15, 3-3, 7-10, 13-55 
options 1-14, 1-17 to 1-20 
-b 1-17to 1-18 
-d 1-17, 1-18 
D_OPTIONS environment variable 
EMU 1-12, 2-12 
-f 1-17, 1-18 
-i 1-17, 1-18 to 1-19, 7-11 
—p 1-17, 1-19 
-profile 1-17, 1-19, 12-3 
-s 1-17, 1-20, 7-10 
-t 1-17, 1-20 


emu5x command (continued) 
-v_ 1-17, 1-20 
-x 1-17, 1-20 
verifying the installation 
DOS EMU 2-13 
OS/2 EMU 1-16 


emuinit.cmd file EMU 1-3, 2-3 
emulation timing calculations EMU 3-10 to 3-12 


emulator 
additional tools EMU 1-3, 2-3 
board.cfg file EMU 1-3 
board.dat file EMU 1-3 
connection to target system EMU 1-8, 2-8, 3-1 
to 3-14 
mechanical dimensions EMU 3-13 to 3-14 
custom switch settings EMU 1-5, 2-5 
debugger environment 
DOS EMU 2-9 to 2-12 
OS/2 EMU 1-9 to 1-14 
debugger installation 
DOS EMU 2-1 to 2-15 
error messages EMU 1-17, 2-14 
OS/2 EMU 1-1 to 1-18 
verifying EMU 1-16, 2-13 
definition E-4 
describing the target system to the 
debugger C-1 to C-5; EMU 1-3, 1-15 
creating the board configuration file C-2 to 
C-5 
specifying the file C-5 
translating the file C-5; EMU 1-3 
$$EMU$$ constant 5-19 
host system EMU 1-2, 2-2 
I/O address space 
DOS EMU 2-4 to 2-5, 2-12 
OS/2 EMU 1-4 to 1-5, 1-12 
installation 
board EMU 1-4 to 1-7, 1-8, 2-4 to 2-7, 2-8 
debugger software EMU 1-9, 2-9 
error messages EMU 1-17, 2-14 
into PC EMU 1-6 to 1-7, 2-6 to 2-7 
preparation EMU 1-4 to 1-5, 2-4 to 2-5 
verifying EMU 1-16, 2-13 
invoking the debugger 3-3, 13-55 
under PDM control 1-15 to 1-16 
memory, default map EMU 1-3, 2-3 
operating system EMU 1-3, 2-3 
requirements 
display EMU 1-2, 2-2 
graphics card EMU 1-2, 2-2 
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emulator, requirements (continued) 
hardware EMU 1-2, 2-2 
memory EMU 1-2, 2-2 
mouse EMU 1-2, 2-2 
power EMU 1-2, 2-2 
software EMU 1-3, 2-3 
resetting EMU 1-3, 1-13, 2-3, 2-12 
screen 
configuration files EMU 1-3, 2-3 
signal buffering EMU 3-7 to 3-9 
switch settings 
DOS EMU 2-4 to 2-5, 2-12 
OS/2 EMU 1-4 to 1-5, 1-12 
target cable EMU 1-7, 2-7 
header design EMU 3-2 to 3-3 
target system EMU 1-2, 2-2 
emurst file EMU 1-3, 1-13, 2-3, 2-12 
definition E-4 
enabling areas 12-10 
endkey SIM2-7 
scrolling 4-27, 13-70 
ENDIF command 5-18 to 5-19, 13-5, 13-24 
See also |F/ELSE/ENDIF commands 
debugger version 13-30 
PDM version 2-10 to 2-14, 13-29 to 13-63 
ENDLOOP command __ 5-20 to 5-21, 13-5, 13-25 
See also LOOP/ENDLOOP commands 
debugger version 13-32 
PDM version 2-11 to 2-12, 13-31 
entering commands 
from menu selections 5-7 to 5-10 
from the PDM_ 1-15, 2-2 
onthe command line 5-2 to 5-6 
entry point 7-12 
enumerated types 
display format 4-16 
environment variables 
D_DIR- 1-15, 5-17, 10-10, 13-50; EVM9 
effects on debugger invocation B-1 
emulator 
DOS EMU 2-11 
OS/2 EMU 1-11 
simulator 
PC systems 1-7 
SPARC systems 2-4 
D_OPTIONS 1-17 to 1-20; EVM 10 
effects on debugger invocation B-1 
emulator 
DOS EMU 2-12 
OS/2 EMU 1-12 
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environment variables, D_ OPTIONS (continued) event (continued) 
simulator counter 
PC systems 1-7 analysis interface 11-16 
SPARC systems 2-5 internal 11-8 
D_SRC_ 1-14, 1-16, 7-11; EVM 10 definition E-4 
effects on debugger invocation B-1 EVM 
emulator additional tools EVM3 
DOS EMU 2-11 custom switch settings EVM5 
OS/2 EMU 1-11 debugger environment EVM 8 to 11 
simulator debugger installation EVM1 to 13 
PC systems 1-7 error messages EVM 13 
SPARC systems 2-4 verifying EVM 12 
definition E-4 definition E-4 
for debugger options 1-17 to 1-20; EVM10 $$EVM$$ constant 5-19 
emulator host system EVM2 
DOS EMU 2-12 I/O address space EVM4,5,10to 11 
Os/2 EMU 1-12 installation 
simulator board EVM4to6 
PC systems 1-7 debugger software EVM7 
SPARC systems 2-5 error messages EVM 13 
identifying auxiliary directories EVM9 into PC EVM6 
emulator preparation EVM4 
DOS EMU 2-11 verifying EVM 12 
OS/2 EMU 1-11 invoking the debugger 3-3 
simulator operating system EVM3 
PC systems 1-7 requirements 
SPARC systems 2-5 display EVM2 
identifying source directories EVM10 graphics card EVM2 
emulator hardware EVM2 
DOS EMU 2-11 memory EVM2 
OS/2 EMU 1-11 mouse EVM2 
simulator power EVM2 
PC systems 1-7 software EVM3 
SPARC systems 2-4 resetting EVM3, 11 
error messages D-1 to D-26 switch settings EVM4, 5, 10 to 11 
beeping 13-54, D-2 $$EVM$$ constant 5-19 
installation EVM13 evm5x command _ 1-14, 3-3, 7-10 
emulator options 1-14, 1-17 to 1-20 
DOS EMU 2-14 —b 1-17to 1-18 
Os/2 EMU 1-17 D_OPTIONS environment variable EVM 10 
EVAL command 8-3, 13-25 i CO 
: —p 1-17, 1-19 
display formats 2-21, 13-26 -s 1-17. 1-20. 7-10 
modifying PC 7-12 -t 1-17 1-20. 
PDM version 2-21, 13-25 -v 1-17, 1-20 
side effects 8-5 =x 1-17 1-20 
event verifying the installation EVM12 
comparators evminit.cmd file EVM3 
counting events 11-9 to 11-10 evmrst fille EVM3, 11 
hardware breakpoints 11-9 to 11-10 definition E-4 
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executing code 3-11, 7-12 to 7-17 

See also run commands 

benchmarking 3-16, 7-13 

checking execution status 2-20, 13-52 

conditionally 3-19 to 3-20, 7-17 

finding execution status 2-8, 13-56 

function key method 13-69 

halting execution 3-14, 7-18 

program entry point 3-15, 3-16, 7-12 to 7-17 

single stepping 3-18, 13-19, 13-20, 13-39, 
13-56 

while disconnected from the target sys- 
tem 7-16, 13-44, 13-48 


executing commands 5-3 


execution 
pausing 2-13, 13-40 


exiting the debugger 1-20, 3-28, 13-45 


expressions 14-1 to 14-6 
addresses 8-7 
evaluation 2-21, 13-25 
by the PDM_ 2-17 
with ?command 8-3, 13-12 
with DISP command 13-22 to 13-25 
with EVAL command 8-3, 13-25 
with LOOP command 5-20, 13-31, 13-32 
expression analysis 14-4 to 14-6 
operators 2-17, 14-2 to 14-3 
restrictions 14-4 
side effects 8-5 
void expressions 14-4 


extensions 1-13 


external clock. See analysis interface, external 
counter 


external event counter 11-11 to 11-12 
analysis interface, interpreting 11-16 


external interrupt 6-16 


external interrupts 
connect input file 6-18 
disconnect pins 6-19 
list pins 6-19 
PINC command 6-18, 13-42 
PIND command 6-19, 13-42 
PINL command 6-19, 13-42 
programming simulator 6-18 to 6-19 
setting up input files 
absolute clock cycle 6-16 
relative clock cycle 6-16 
repetition 6-17 
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-f debugger option 1-17, 1-18, C-5 

with D-OPTIONS environment variable 
EMU 1-12 

F1 key 
mapping S/M2-7 

F2 key 5-5, 13-67 
mapping S/M2-7 

F3 key 7-3, 13-68 
mapping S/M2-7 

F4 key 3-21, 3-23, 4-10, 4-15, 4-29, 8-15, 13-69 
mapping S/M2-7 

F5 key 5-10, 7-13, 13-9, 13-69 
mapping S/M2-7 

F6 key 3-6, 4-20, 8-4, 13-69 
mapping S/M2-7 

F7 key 
mapping S/M2-7 

F8 key 5-10, 7-15, 13-9, 13-69 
mapping S/M2-7 

F9 key 3-23, 3-26, 4-7, 4-8, 4-9, 4-10, 4-28, 7-9, 
8-5, 8-15, 9-3, 9-4, 13-70 
mapping S/M2-7 

F10 key 5-10, 7-15, 13-9, 13-69 
mapping S/IM2-7 

FILE command 3-11, 3-14, 7-8, 13-26 
changing the current directory 5-25, 13-18 
effect on debugging modes 4-4 
effect on FILE window 4-8 
menu selection 13-9 

FILE window 3-11, 3-14, 4-5, 4-8, 7-2, 7-4, 7-8 
colors 10-5 
customizing 10-5 
definition E-4 

file/load commands 13-6 
ADDRcommand_ 7-5, 7-9, 7-12, 13-14 
CALLS command 4-9, 4-10, 7-9, 13-18 
DASM command 7-5, 7-12, 13-21 
FILE command 3-11, 3-14, 7-8, 13-26 
FUNC command 3-14, 7-8, 13-27 
LOAD command _ 3-4, 7-10, 13-30 
menu selections 13-9 
PATCH command 7-5, 13-40 
RELOAD command 7-10, 13-46 
RESTART command 3-15, 3-16, 13-46 
SLOAD command 7-10, 13-54 
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files 
connecting to I/O ports 6-11, 13-34 
disconnecting from I/O ports 6-15, 13-36 to 
13-37 
log files 2-10, 5-6 to 5-8, 13-23 
saving memory to afile 8-10, 13-39 
FILL command 8-11, 13-26 
menu selection 13-10 
floating point 
display format 3-24 to 3-25, 4-16 
Operations 14-4 
FO control bit 13-34 
font 
changing the debugger display S/M 2-8 
FUNC command 3-14, 7-8, 13-27 
effect on debugging modes 4-4 
effecton FILE window 4-8 
function calls 
displaying functions 13-27 
keyboard method 4-10 
mouse method 4-10 
executing function only 13-47 
in expressions 8-5, 14-4 
stepping over 13-19, 13-39 
tracking in CALLS window 4-9 to 4-10, 7-9, 
13-18 


—gshelloption 1-12, 1-13, 12-2 
global breakpoints 11-12 
GO command 3-11, 7-13, 13-27 
graphics card requirements EVM 2; SIM 1-2 
emulator 
DOS EMU 2-2 
OS/2. EMU 1-2 
grouping/reference operators 14-2 
groups 
adding aprocessor 2-4, 13-51 
commands 
SET command 2-3 to 2-5, 13-51 to 13-52 
UNSET command 2-5, 13-59 
defining 2-3 to 2-5, 13-51 
deleting 2-5, 13-59 
examples 2-3 
identifying 2-2 to 2-5 
listing all groups 2-5, 13-51 
setting default 2-4, 13-51 
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HALT command 7-16, 13-28 
halting 
batch file execution 5-17 
debugger 1-20, 3-28, 13-45 
PDM 1-20, 13-45 
processors in parallel 2-8, 13-41 
program execution 1-20, 3-14, 7-12, 7-18, 
13-45 
function key method 7-18, 13-68 
mouse method 7-18 
target system 13-28 
hardware breakpoints. See breakpoints (hardware) 
hardware checklist EVM2 
emulator 
DOS EMU 2-2 
OS/2 EMU 1-2 
simulator 
PC systems SIM 1-2 
SPARC systems SIM 2-2 
hardware stacks, accessing 8-13 
HELP command 13-28 
hex conversion utility 1-11 
hexadecimal notation 
addresses 8-7 
data formats 8-19 
history 
ofcommands 2-13 to 2-14, 5-5, 13-13 
HISTORY command 2-14, 13-28 
home key S/M2-7 
scrolling 4-27, 13-70 
host system EVM2 
DOS EMU2-2 
OS/2. EMU 1-2 
PC systems S/M1-2 
SPARC systems SIM 2-2 


-i debugger option 1-17, 1-18 to 1-19, 7-11 
with D-OPTIONS environment variable EVM 10 

emulator 
DOS EMU 2-12 
OS/2 EMU 1-12 

simulator 
PC systems SIM 1-7 
SPARC systems SIM 2-5 


I/O address space EVM4,5,10to 11 
emulator 
DOS EMU 2-4 to 2-5, 2-12 
OS/2 EMU 1-4 to 1-5, 1-12 
1/O memory 
adding to memory map 6-5, 13-32 to 13-33 
deleting from memory map 6-9, 13-35 
simulating 6-11 to 6-15, 13-34, 13-36 to 13-37 
I/O switch settings 
default settings EVM4,5 
emulator 
DOS EMU 2-4 to 2-5 
OS/2 EMU 1-4 to 1-5 
definition E-4 
icons 
method identification v 
mouse actions vi 
IF/ELIF/ELSE/ENDIF commands 2-10 to 2-14, 
13-29 to 13-63 
IF/ELSE/ENDIF commands _ 5-18 to 5-19, 13-5, 
13-30 
conditions 5-21, 13-30 
creating initialization batch file 5-19 
predefined constants 5-19 
increment operator 14-3 
index numbers 
for data in WATCH window 4-17, 8-17 
indirection operator (*) 8-9, 8-17 
init.clr file 10-9, 10-10, 13-50, B-1; EMU 1-3, 2-3; 
EVM 3; SIM 1-3, 3-2 
init.cmd 
definition E-4 
init.cmd file 6-2, B-1 
init.pdm file 1-15 
initdb.bat file EMU 2-9 to 2-12; EVM 8 to 11; 
SIM 1-5 to 1-7 
definition E-4 
invoking EMU 2-10; EVM9; SIM 1-6 
sample EMU 2-10; EVM8; SIM 1-5 
initdb.cmd file EMU 1-9 to 1-14 
invoking EMU 1-10 
limitations EMU 1-11, 1-12 
sample EMU 1-10 
initialization batch files 6-2, 6-3, B-1 
creating using IF/ELSE/ENDIF 5-19 
emuinit.cmd EMU 1-3, 2-3 
evminit.cmd EVM3 
init.cmd 6-2, B-1 


Index 


initialization batch files (continued) 


initppdm 1-15 


naming an alternate file 1-17, 1-20 


siminit.cmd 
PC systems 


SIM 1-3 


SPARC systems SIM 2-2 
insert key SIM 2-7 


installation 
board EVM4 


to6 


debugger software EVM7 
DOS EMU2-9 
OS/2 EMU 1-9 


PC systems 


SIM 1-4 


SPARC systems SIM 2-3 


emulator 


DOS EMU 2-4 to 2-7 
OS/2 EMU 1-4 to 1-7 


error messages 


EVM 13 


DOS EMU 2-14 
OS/2 EMU 1-17 
verifying EVM12 
DOS EMU 2-13 
OS/2 EMU 1-16 


PC systems 


SIM 1-8 


SPARC systems SIM 2-6 


instruction fetches 


11-8 


See also analysis interface 


integer 
display format 


4-16 


SETF command 8-19 


internal event counter 11-6 
analysis interface 


interpreting 
interrupt pins 6-1 
interrupts 


11-16 
6 to 6-19 


receive 6-13, 13-34 


taken 11-8 


See also analysis interface 


transmit 6-13, 


13-34 


invalid memory addresses 6-3, 6-7 


invoking 


autoexec.bat file EMU 2-10; EVM9; SIM1-6 


config.sys file 


EMU 1-10 


.cshrc file SIM 2-5 
custom displays 10-11 


debugger 3-3, 
standalone 


13-55 
1-14 


under PDM control 1-15 to 1-16 


initdb.bat file 


EMU 2-10; EVM9; SIM 1-6 
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invoking (continued) 
initdb.cmd file EMU 1-10 
parallel debug manager 1-15 
shell program 1-13 


IOPL 

setting EMU1-13 
ISA 

definition E-4 


key sequences 
displaying functions 13-70 
displaying previous commands (command 
history) 13-67 
editing 
command line 5-3, 13-67 
data values 4-28, 13-70 
halting actions 2-6, 2-7, 13-44, 13-51, 13-68 
menu selections 13-68 
moving awindow 4-25, 13-69 
opening additional DISP windows 13-70 
running code 13-69 
scrolling 4-27, 13-70 
selecting the active window 4-20, 13-69 
setting/clearing software breakpoints 13-70 
single stepping 7-15 
sizing a window 4-23, 13-69 
switching debugging modes_ 13-68 


keyboard 
mapping keys SIM 2-7 
keys 
special keys with the X Window System 
SIM 2-7 


keysym label S/M 2-7 


labels 
for data in WATCH window 3-17, 4-17, 8-17 
keysym SIM 2-7 


limitations 
initdb.cmd file EMU 1-11, 1-12 
limits 
breakpoints 9-2 
file size 7-9 
open DISP windows 4-16 
paths 7-11 
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limits (continued) 
window positions 4-25, 13-38 
window sizes 4-22, 13-53 
linker 1-11, 1-12; EMU 1-3, 2-3; EVM3; SIM 1-3, 
3-2 
command files, MEMORY definition 6-2 
LOAD command __ 3-4, 7-10, 13-30 
effect on DISP window 8-15 
effect on WATCH window 8-17 
load/file commands 13-6 
ADDR command _ 7-5, 7-9, 7-12, 13-14 
CALLS command 4-9, 4-10, 7-9, 13-18 
DASM command 7-5, 7-12, 13-21 
FILE command 3-11, 3-14, 7-8, 13-26 
FUNC command 3-14, 7-8, 13-27 
LOAD command 3-4, 7-10, 13-30 
menu selections 13-9 
PATCH command 7-5, 13-40 
RELOAD command 7-10, 13-46 
RESTART command 3-15, 3-16, 13-46 
SLOAD command 7-10, 13-54 
loading 
batch files 5-17 
COFF files, restrictions 6-3 
custom displays 10-10 
object code 3-3, 7-10 
after invoking the debugger 7-10 
symbol table only 7-10, 13-54 
while invoking the debugger 1-14, 1-16, 7-10 
without symbol table 7-10, 13-46 
log files 2-10, 5-6 to 5-8, 13-23 
logical operators 14-2 
conditional execution 7-17 
LOOP/BREAK/CONTINUE/ENDLOOP com- 
mands 2-11 to 2-12, 13-31 
LOOP/ENDLOOP commands 5-20 to 5-21, 13-5, 
13-32 
conditions 5-21, 13-32 
looping commands 2-11 to 2-12, 5-20 to 5-21, 
13-31, 13-32 


MA command 3-27, 6-4, 6-5, 6-9, 13-32 to 13-33 
menu selection 13-10 

managing data 8-1 to 8-21 
basic commands 8-2 to 8-3 

MAP command 6-7, 13-33 
menu selection 13-10 


mapping. See memory, mapping 
mapping keys for use with X Windows SIM 2-7 
marking areas 12-5 to 12-7 


MC command 6-11, 13-34 
menu selection 13-10 


MD command 3-27, 6-9, 13-35 
menu selection 13-10 


MEM command 3-5, 4-12, 4-13, 4-14, 4-15, 8-7, 
13-35 to 13-36 
display formats 3-25, 8-21, 13-36 
effect on debugging modes 4-4 


MEM1 command 4-12 
See also MEM command 


MEM2 command 4-12 
See also MEM command 


MEMS3 command 4-12 
See also MEM command 


memory 
batch file search order 6-2, B-1 
commands 13-7 
FILL command 8-11, 13-26 
menu selections 13-10 
MS command 8-10, 13-39 
dataformats 8-19 
datamemory 3-27, 4-13 to 4-15 
default map 3-27, 6-3; EVM3 
DOS EMU 2-3 
OS/2 EMU 1-3 
PC systems SIM 1-3 
SPARC systems SIM 2-2 
displaying in different numeric format 3-24 to 
3-25, 8-9 
filling 8-11, 13-26 
invalid addresses 6-3 
invalid locations 6-7 
map 
adding ranges 13-32 to 13-33 
defining 6-2 
in abatch file 6-2 
interactively 6-2 
definition E-4 
deleting ranges 13-35 
modifying 6-2 
potential problems 6-3 
resetting 13-38 
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memory (continued) 
mapping 3-27, 3-28, 6-1 to 6-19; EVM3 
adding ranges 6-5 
commands 13-7 
MA command 3-27, 6-4, 6-5, 6-9, 13-32 to 
13-33 
MAP command 6-7, 13-33 
MD command 3-27, 6-9, 13-35 
menu selections 13-10 
ML command 3-27, 6-8, 13-37 
MRcommand 6-9, 13-38 
deleting ranges 6-9 
disabling 6-7 
emuinit.cmd file EMU 1-3, 2-3 
evminit.cmd file EVM3 
listing current map 6-8 
modifying 6-9 
multiple maps 6-10 
PC systems SIM 1-3 
resetting 6-9 
returning to default 6-10 
siminit.cmd file 
PC systems S/IM1-3 
SPARC systems SIM 2-2 
simulating /O ports 6-11, 6-15, 13-34, 13-36 
to 13-37 
SPARC systems SIM 2-2 
nonexistent locations 6-2 
program memory 3-27, 4-13 to 4-15, 8-8 
protected areas 6-3, 6-7 
requirements EVM2; SIM1-2 
DOS EMU 2-2 
OS/2 EMU 1-2 
saving 8-10, 13-39 
simulating 
VOmemory 6-11 to 6-15, 13-34, 13-36 to 
13-37 
ports 
MC command 6-11, 13-34 
menu selections 13-10 
Ml command 6-15, 13-36 to 13-37 
undefined areas 6-3, 6-7 
valid types 6-5 


memory cache S/M4-1 


MEMORY window _ 3-5, 4-5, 4-12 to 4-15, 8-2, 8-6 
to 8-11, 13-35 to 13-36 
additional MEMORY windows 4-13 to 4-15 
address columns 4-12 
closing 4-15 
colors 10-6 
customizing 10-6 


Index-17 


Index 


MEMORY window (continued) 
datacolumns 4-12 
datamemory 4-13 
definition E-4 
displaying 

different memory range 4-14 
memory contents 8-6 to 8-8 
program memory 8-8 
editing memory contents 8-4 
modifying display 13-35 to 13-36 
opening additional windows 4-13 to 4-14, 4-15 
program memory 4-13 


MEMORY1 window 4-13 to 4-15 
See also MEMORY window 
closing 4-15 
opening 4-13 


MEMORY2 window 4-13 to 4-15 
See also MEMORY window 
closing 4-15 
opening 4-13 


MEMORYS3 window 4-13 to 4-15 
See also MEMORY window 
closing 4-15 
opening 4-13 


memory-map commands 
See also memory, mapping, commands 
menu selections 13-10 


menu bar 3-4, 5-7 
customizing its appearance 10-7 
definition E-4 
items without menus 5-10 
using menus 5-7 to 5-10 


menu selections 5-7, 13-9 to 13-11 
colors 10-7 
customizing their appearance 10-7 
definition (pulldown menu) E-5 
entering parameter values 5-11 
escaping 5-9 
function key methods 5-9, 13-68 
listof menus 5-7 
mouse methods 5-8 to 5-9 
moving to another menu 5-9 
profiling 5-8, 12-4 
usage 5-8 to 5-9 
messages D-1 to D-26 
installation errors EVM13 
DOS EMU 2-14 
OS/2 EMU 1-17 
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Ml command 6-15, 13-36 to 13-37 
menu selection 13-10 
MIX command 3-13, 7-3, 13-37 
menu selection 7-3, 13-11 
mixed mode 3-12 to 3-13, 4-4, 7-2 
definition E-5 
MIX command 3-13, 7-3, 13-37 
selection 7-3 
ML command 3-27, 6-8, 13-37 
menu selection 13-10 
modes. See debugging modes 
modifying 
assembly language code 7-5 to 7-6 
colors 10-2 to 10-7 
commandline 5-3 
command-line prompt 10-12 
current directory 5-25, 13-18 
datavalues 8-4 
memory map 6-2, 6-9 
window borders 10-8 
mono.clr file 10-9; EMU 1-3, 2-3; EVM3 
PC systems S/M1-3 
SPARC systems SIM 2-2 
monochrome monitors 10-9 
color mapping with X Windows S/M 2-8 
mouse 
cursor 4-18 
icon identification vi 
requirements EVM2 
DOS EMU 2-2 
OS/2 EMU 1-2 
PC systems SIM 1-2 
MOVE command 3-9, 4-24, 13-38 
effect on entering other commands _ 5-4 
moving awindow 4-24 to 4-26, 13-38 
function key method 3-9, 4-25, 13-69 
mouse method 3-9, 4-24 
MOVE command 3-9, 4-24 
XY screen limits 4-25, 13-38 
MRcommand 6-9, 13-38 
menu selection 13-10 
MS command 8-10, 13-39 
menu selection 13-10 
MS-DOS 
See also DOS; system commands 
entering from the command line 5-24 
exiting from system shell 13-57 to 13-59 
SYSTEM command _ 5-24, 13-57 to 13-59 


MS-Windows 
using with the debugger EMU 2-9, 2-15; EVM 
7,13; SIM 1-4, 2-9 
—mv debugger option 1-17, 1-19 
with DLOPTIONS environment variable S/M 
1-7, 3-5 


—n debugger option 1-16, 2-2, 13-55; EMU 1-16 

with D-OPTIONS environment variable EMU 
1-12 

natural format 3-24 to 3-25, 14-5 

NEXT command 3-18, 7-15, 13-39 
from the menu bar 5-10 
function key entry 5-10, 13-69 

nonexistent memory locations 6-2 


object files 
creating 7-10 
loading 1-14, 1-16, 13-30 
after invoking the debugger 7-10 
symbol table only 1-17, 1-20, 13-54 
while invoking the debugger 1-14, 1-16, 3-3, 
7-10 
without symbol table 7-10, 13-46 
open-collector output 
definition E-5 
operating system EVM3 
DOS EMU2-3 
Os/2. EMU 1-3 
PC systems S/M1-3 
SPARC systems SIM 2-2 
operators 2-17, 14-2 to 14-3 
& operator 8-7 
* operator (indirection) 8-9, 8-17 
side effects 8-5 
optional files EMU 1-3, 2-3; EVM3 
PC systems S/M1-3 
SPARC systems SIM 2-2 
OS/2 
display requirements EMU 1-2 
error messages 
installation EMU 1-17 
graphics card requirements EMU 1-2 
hardware requirements EMU 1-2 
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OS/2 (continued) 
host system EMU 1-2 
memory requirements EMU 1-2 
mouse requirements EMU 1-2 
operating system EMU 1-3 
power requirements EMU 1-2 
setting up debugger environment EMU 1-9 to 
1-14 
software requirements EMU 1-3 
target system EMU 1-2 
overwrite editing 8-4 to 8-5 


—p debugger option 1-17, 1-19 
with D-OPTIONS environment variable EVM 
10 
DOS EMU 2-12, 2-14 
OS/2 EMU 1-12, 1-14, 1-17 
page-up/page-down keys SIM 2-7 
scrolling 4-27, 13-70 
parallel debug manager 2-1 
adding aprocessor to agroup 2-4, 13-51 
assigning processor names 2-2 
—noption 1-16, 2-2, 13-55 
changing the PDM prompt 2-19, 13-52 
checking the execution status 2-20, 13-52 
closing 1-20, 13-45 
command history 2-13 to 2-14, 13-13 
commands 13-3 
!command 2-13 to 2-14, 13-13 
@command 2-19, 13-13 
ALIAS command 2-15 to 2-16, 13-15 
DLOG command 2-10, 13-23 
ECHO command 2-12, 13-24 
EVAL command 2-21, 13-25 
HELP command 13-28 
HISTORY command 2-14, 13-28 
IF/ELIF/ELSE/ENDIF commands 2-10 to 
2-14, 13-29 to 13-63 
LOOP/BREAK/CONTINUE/ENDLOOP com- 
mands 2-11 to 2-12, 13-31 
PAUSE command 2-13, 13-40 
PDM command 1-15 
PESC command 2-8, 13-40 
PHALT command 2-8, 13-41 
PRUN command 2-7, 13-44 
PRUNF command 2-7 
PSTEP command 2-7, 13-45 
QUIT command 1-20, 13-45 
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Index 


parallel debug manager, commands (continued) parameters 
RUNF command 13-44 dspcl shell 1-13 
SEND command 2-6, 13-50 to 13-51 entering in a dialog box 5-11 to 5-12 
SET command 2-3 to 2-5, 13-51 to 13-52 patch assembly 7-5 
creating system variables 2-18 to 2-19 predefined 5-13 
SPAWN command 1-15 to 1-16, 13-55 enabling 5-13 
STAT command 2-8, 2-20, 13-52, 13-56 function key method 5-14to 5-15 


mouse method 5-14 


SYSTEM command 2-16 é : 
TAKE d 2-9. 13-58 selecting from dialog boxes 5-12 
une hee simpp command 1-14 


UNALIAS command 2-15 to 2-16 SPAWN command 1-15 to 1-16, 13-55 
ONSET Command 29,1990 PATCH command 7-5, 13-40 


deleting system variables 2-20 ; . 
path environment variable 1-15 


viewing descriptions 13-28 
controlling command execution 2-10 to 2-14 ooo 1-15, 13-55; EVM 9; SIM 1-6, 


creating system variables 2-18 to 2-19, 13-52 DOS EMU2-11 
concatenating stri 2-18 3 
ncatenating strings 08/2 EMU 1-11 


substituting strings 2-19 
defining a group 2-3 to 2-4, 13-51 PAUSE command 2-13, 13-40 


definition E-5 PC 7-12 
deleting a group 2-5, 13-59 definition E-5 
UNSET command 2-5, 13-59 discontinuity 


f . description 11-3 
delet les 2-2 
ee ee interpreting 11-14 to 11-16 


description 18 : displaying contents of 3-5 
displaying text strings 2-12, 13-24 finding the current PC 4-7 
expression analysis 2-17 PDM 

finding the execution status 2-8, 13-56 wocation 12 


global halt 2-8, 13-41 
grouping processors 2-2 to 2-5 PRP rQMman). ares 
PESC command 2-8, 13-40 


example 2-3 


SET command 2-3 to 2-5, 13-51 to 13-52 PFcommand 12-15, 13-41 
halting code execution 2-8, 13-40 effecton PROFILE window 4-11 
invoking 1-15 PHALT command 2-8, 13-41 
listing all groups of processors 2-5, 13-51 pin commands 
listing system variables 2-20 menu selection 13-11 
messages D-22 to D-26 PINC command 6-18 
overview 1-15 menu selection 13-11 
pausing 2-13, 13-40 PIND command 6-19 
recording information from the display menu selection 13-11 
area 2-10, 13-23 PINL command 6-19 
running code 2-7, 13-44 menu selections 13-11 
running free 2-7 pipeline clocks 11-8 
sending commands to debuggers 2-6, 13-50 to pointers 
13-51 displaying/modifying contents 3-22, 8-14 
setting the default group 2-4, 13-51 format in DISP window 3-22, 4-16, 8-14, 13-22 
single-stepping through code 2-7, 13-45 natural format 14-5 
supported operating systems 1-15 typecasting 14-5 
system variables 2-18 to 2-20 pointing 
using with UNIX 1-15 definition E-5 
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portaddress 1-17, 1-19; EVM10 
D_ OPTIONS EVM10 
DOS EMU2-12 
OS/2 EMU 1-12 
definition E-5 
DOS EMU2-14 
OS/2 EMU 1-14, 1-17 
simulator 6-11 to 6-15 


ports 
simulating 6-11 to 6-15, 13-34 to 13-70 


power requirements 
board EMU 1-2, 2-2; EVM2 


PQcommand 12-15, 13-42, 13-43 
effect on PROFILE window 4-11 


PRcommand. 12-16, 13-43 


processors 
assigning names 2-2 
organizing into groups 2-3 to 2-5 
—profile debugger option 1-17, 1-19 
with D-OPTIONS environment variable 
emulator 
DOS EMU 2-12 
OS/2 EMU 1-12 
simulator 
PC systems SIM 1-7 
SPARC systems SIM 2-5 


PROFILE window 4-5, 4-11, 12-17 to 12-21 
associated code 12-21 
data accuracy 12-19 
displaying areas 12-19 to 12-20 
displaying different data 12-17 to 12-18 
sorting data 12-19 
profiling 12-1 to 12-22 
collecting statistics 
full statistics 12-15, 13-41 
subset of statistics 12-15, 13-42, 13-43 
commands 13-8 
PF command 12-15, 13-41 
PQcommand 12-15, 13-42, 13-43 
PRcommand 12-16, 13-43 
SAcommand 12-14, 13-48 
SD command 12-14, 13-50 
SL command 12-14, 13-54 
SRcommand 12-14, 13-55 
summary 13-64 to 13-66 
VAA command 12-22, 13-59 
VAC command 12-22, 13-60 
VRcommand 13-60 
compiling a program for profiling 12-2 
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profiling (continued) 


defining areas 12-5 to 12-12 
disabling areas 12-7 to 12-9 
function key method 12-9 
mouse method 12-8 
enabling areas 12-10 
function key method 12-10 
marking areas 12-5 to 12-7 
function key method 12-7 
mouse method 12-6 
restrictions 12-12 to 12-17 
unmarking areas 12-11 to 12-12 
function key method 12-12 
mouse method 12-11 
description 1-6 to 1-7 
entering environment 12-3 
key features 1-6 to 1-7 
menu selections 5-8, 12-4 
overview 12-2 
resetting PROFILE window 13-60 
restrictions 
available windows 12-3 
batch files 12-3 
breakpoints 12-3 
commands 12-3 
modes 12-3 
resuming asession 12-16, 13-43 
running asession 12-15 to 12-16 
full 12-15, 13-41 
quick 12-15, 13-42, 13-43 
saving datatoafile 12-22 
saving statistics 
all views 12-22, 13-59 
current view 12-22, 13-60 
stopping points 12-13 to 12-14 
adding 12-14, 13-48 
command method 12-14 
deleting 12-14, 13-50, 13-55 
listing 12-14, 13-54 
mouse method 12-13 
resetting 12-14, 13-55 
strategy 12-2 
viewing data 12-17 to 12-21 
associated code 12-21 
data accuracy 12-19 
displaying areas 12-19 to 12-20 
displaying differentdata 12-17 to 12-18 
sorting data 12-19 
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program 
debugging 1-21 
entry point 7-12 
resetting 13-46 
execution, halting 1-20, 3-14, 7-12, 7-18, 13-45, 
13-68 
preparation for debugging 1-12 to 1-13 


program counter (PC) 8-12 


program memory 4-13 to 4-15 
adding to memory map 6-5, 13-32 to 13-33 
deleting from memory map _ 6-9, 13-35 
displaying 8-8 
filling 8-11, 13-26 
saving 8-10, 13-39 


PROMPT command 10-12, 13-43 
menu selection 13-11 


protocol 
bus EMU3-3 


PRUN command 2-7, 13-44 
PRUNF command 2-7 


pseudoregisters 
See also registers 
daddr 8-18 
dins 8-18 
faddr 8-18 
fins 8-18 
raddr 8-18 
rins 8-18 
xaddr 8-18 
xins 8-18 
PSTEP command 2-7, 13-45 
with breakpoints 2-7 
pulldown menus 


See also menu selections 
definition E-5 


qualifiers 
predefined 5-13 
enabling 5-14 
function key method 5-14 to 5-15 
mouse method 5-14 
selecting from dialog boxes 5-12 


QUIT command 1-20, 3-28, 13-45 
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RAM 
speed EMU 1-2 
recording COMMAND window displays 5-6 to 5-8, 
13-5, 13-23 
reentering commands _ 5-5, 13-67 
registers 
ARO 8-12 
CLK pseudoregister 3-16, 7-19 
displaying/modifying 8-12 to 8-13 
DRR_ 6-13, 13-34 
DXR_ 6-13, 13-34 
pipeline pseudoregisters 
dadar 8-18 
dins 8-18 
faddr 8-18 
fins 8-18 
radar 8-18 
rins 8-18 
xadar 8-18 
xins 8-18 
program counter (PC) 8-12 
referencing byname 14-4 
STO 8-12 
TDXR_ 6-13, 13-34 
TRCV 6-13, 13-34 
relational operators 14-2 
conditional execution 7-17 
relative pathnames 5-25, 7-11, 13-18 
RELOAD command 7-10, 13-46 
menu selection 13-9 
repeating commands 2-13 to 2-14, 5-5, 13-13, 
13-67 
required files EMU 1-3, 2-3; EVM3 
required tools EMU 1-3, 2-3; EVM3 
PC systems S/M1-3 
SPARC systems SIM 2-2 
RESET command _ 3-4, 7-16, 13-46 
menu selection 13-9 
resetting EVM3, 11 
emurst file EMU 1-3, 1-13, 2-3, 2-12 
memory map 13-38 
program entry point 13-46 
target system 3-4, 7-16, 13-46 
RESTART (REST) command 3-15, 3-16, 7-12, 
13-46 
menu selection 13-9 


restrictions 
See also limits; constraints 
breakpoints 9-2 
C expressions 14-4 
debugging modes 4-4 
profiling environment 12-3 
SSAVE command 10-10 


RETURN (RET) command 7-13, 13-47 


returns taken 11-8 
See also analysis interface 


ripple-carry output signal 
definition E-5 


RUN command 3-14, 7-13, 13-47 
analysis interface 11-13 
from the menu bar 5-10 
function key entry 5-10, 7-13, 13-69 
menu bar selections 5-10 
with conditional expression 3-19 


runcommands' 13-7 
CNEXT command 7-15, 13-19 
conditional parameters 3-19 
CSTEP command 3-18, 7-15, 13-20 
GO command 3-11, 7-13, 13-27 
HALT command 7-16, 13-28 
menu bar selections 5-10, 13-9, 13-69 
NEXT command 3-18, 7-15, 13-39 
PESC command 2-8, 13-40 
PHALT command 2-8, 13-41 
PRUN command 2-7, 13-44 
PRUNF command 2-7 
PSTEP command 2-7, 13-45 
RESET command 3-4, 7-16 
RESTART command 3-15, 3-16, 7-12 
RETURN command 7-13, 13-47 
RUN command 3-14, 7-13, 13-47 
RUNB command 3-16, 7-13, 7-19, 13-48 
RUNF command 7-16, 13-44, 13-48 
STEP command 3-18, 7-14, 13-56 


RUNB command 3-16, 7-13, 7-19, 13-48 
RUNF command 7-16, 13-44, 13-48 


running programs 7-12 to 7-17 
conditionally 7-17 
halting execution 7-18 
program entry point 7-12 to 7-17 
while disconnected from the target system 7-16 
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—s debugger option 1-17, 1-20, 7-10 
with D-OPTIONS environment variable 
EVM 10; SIM 1-7, 3-5 
DOS EMU 2-12 
OS/2. EMU 1-12 


SAcommand 12-14, 13-48 
saving custom displays 10-9 


scalar type 
definition E-5 
scan path linker C-3 
device type C-3 
example C-4 


SCOLOR command 10-2, 13-49 to 13-50 
menu selection 13-11 


SCONFIG command 10-10, 13-50 
menu selection 13-11 
restrictions 10-10 


screen-customization commands 13-6 
BORDER command 10-8, 13-17 
COLOR command 10-2, 13-19 to 13-20 
menu selections 13-11 
PROMPT command 10-12, 13-43 
SCOLOR command 10-2, 13-49 to 13-50 
SCONFIG command 10-10, 13-50 
SSAVE command 10-9, 13-56 


scrolling 3-10, 4-26 to 4-27 
definition E-6 
function key method 3-10, 4-27, 13-70 
mouse method 3-10, 4-26 to 4-27, 8-8 


SD command 12-14, 13-50 
SEND command 2-6, 13-50 to 13-51 


serial ports 
simulation 6-11 to 6-15, 13-34 
TDM mode 6-12, 13-34 


SET command 2-3 to 2-5, 13-51 to 13-52 
adding processors to agroup 2-4, 13-51 
changing the PDM prompt 2-19, 13-52 
creating system variables 2-18 to 2-19, 13-52 

concatenating strings 2-18 
substituting strings 2-19 
defining agroup 2-3 to 2-4, 13-51 
defining the default group 2-4, 13-51 
listing allgroups 2-5, 13-51 
listing system variables 2-20 
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SETF command 3-24 to 3-25, 8-19 to 8-22, 13-52 
to 13-53 


shell program 1-13 


side effects 8-5, 14-3 
definition E-6 
valid operators 8-5 


signal buffering for emulator connections EMU 3-7 


to 3-9 
$$SIM$$ constant 5-19 


sim5x command 1-14, 3-3, 7-10 
options 1-14, 1-17 to 1-20 
-b 1-17to 1-18 
-d 1-17, 1-18 
D_OPTIONS environment variable SIM 1-7, 
3-5 

-i 1-17, 1-18 to 1-19, 7-11 
—mv 1-17, 1-19 
-profile 1-17, 1-19, 12-3 
-s 1-17, 1-20, 7-10 
-t 1-17, 1-20 
-v 1-17, 1-20 
-x 1-17, 1-20 


verifying the installation S/M 1-8, 3-6 


sim5x directory 
PC systems SIM 1-7 
SPARC systems SIM 2-3, 3-4 


siminit.cmd file 
PC systems S/M1-3 
SPARC systems SIM 2-2 


simulating interrupts 6-16 to 6-19 


simulator 
accessing hardware stacks 8-13 
BIO simulation 8-18 
definition E-6 
/Omemory 6-11 to 6-15, 13-34, 13-36 to 13-37 
invoking the debugger 3-3 
standalone 1-14 
PC systems 
additional tools SIM 1-3 
debugger environment SIM 1-5 to 1-7 
debugger installation SIM 1-1 to 2-9 
verifying S/IM1-8 
host system SIM 1-2 
installation 
software S/M1-4 
verifying S/IM1-8 
operating system SIM 1-3 
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simulator, PC systems (continued) 
requirements 
display S/IM1-2 
graphics card S/M1-2 
hardware S/M1-2 
memory S/M1-2 
mouse S/M1-2 
software S/M1-3 
pipeline simulation 8-18 
$$SIM$$ constant 5-19 
SPARC systems 
additional tools SIM 2-2 
debugger environment SIM 2-4 to 3-5 
debugger installation SIM 2-1 to 2-8 
verifying SIM 2-6 
host system SIM 2-2 
installation 
software SIM 2-3 
verifying SIM 2-6 
operating system SIM 2-2 
requirements 
display SIM 2-2 
hardware S/M2-2 
software SIM2-2 


single-step 
commands 
CNEXT command 7-15, 13-19 
CSTEP command 3-18, 7-15, 13-20 
menu bar selections 5-10 
NEXT command 3-18, 7-15, 13-39 
PSTEP command 2-7, 13-45 
STEP command 3-18, 7-14, 13-56 
definition E-6 
execution 7-14 
assembly language code 7-14, 13-56 
Ccode 7-15, 13-20 
function key method 7-15, 13-69 
in parallel 2-7, 13-45 
with breakpoints 2-7 
mouse methods 7-15 
over function calls 7-15, 13-19, 13-39 


SIZE command 3-7, 4-22, 13-53 to 13-54 
effect on entering other commands 5-4 


sizeof operator 14-4 


sizes 
display 4-25, 13-38 
displayable files 7-9 
windows 4-22, 13-53 


sizing awindow 4-21 to 4-23 
function key method 3-7, 4-23, 13-69 
mouse method 3-7, 4-22 
SIZE command 3-7, 4-22 
size limits 4-22, 13-53 
while moving it 4-25, 13-38 
SL command 12-14, 13-54 


SLOAD command 7-10, 13-54 
effect on DISP window 8-15 
effect on WATCH window 8-17 
menu selection 13-9 
—s debugger option 1-17, 1-20 

software breakpoints. See breakpoints (software) 

software checklist EVM3 
DOS EMU2-3 
Os/2. EMU 1-3 
PC systems S/M1-3 
SPARC systems SIM 2-2 

Solaris 2.x  S/IM4-1 

SOUND command 13-54, D-2 

SPAWN command 1-15 to 1-16, 13-55 
options 1-16, 1-17 to 1-20 

-b 1-17 to 1-18 
-d 1-17, 1-18 

-f 1-17, 1-18 

-i 1-17, 1-18 to 1-19 
—n 1-16, 13-55 
—p 1-17, 1-19 
-profile 1-17, 1-19 
-s 1-17, 1-20 

-t 1-17, 1-20 

-v_ 1-17, 1-20 

-x 1-17, 1-20 

SPC control bit 13-34 

special keys 
X Window System SIM 2-7 

SPL device type C-3 

SRcommand 12-14, 13-55 


SSAVE command 10-9, 13-56 
menu selection 13-11 


STO register 8-12 

startup.cmd file EMU 1-13 

STAT command 2-8, 2-20, 13-52, 13-56 
status register (ST) 8-12 


STEP command 3-18, 7-14, 13-56 
from the menu bar 5-10 
function key entry 5-10, 13-69 
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stopping points 12-13 to 12-14 
adding 12-14, 13-48 
deleting 12-14, 13-50, 13-55 
listing 12-14, 13-54 
resetting 12-14, 13-55 
structures 
direct reference operator 14-2 
displaying/modifying contents 8-14 
format in DISP window 3-23, 8-14, 13-22 
indirect reference operator 14-2 
switch settings 
default settings EVM4,5 
DOS EMU 2-4 to 2-5 
OS/2 EMU 1-4 to 1-5 
I/O address space 1-17, 1-19; EVM5, 10 to 11 
DOS EMU 2-4 to 2-5, 2-12 
OS/2 EMU 1-4 to 1-5, 1-12 
your settings EVM5 
DOS EMU2-5 
OS/2 EMU 1-5 
symbol table 
definition E-6 
loading without object code 1-17, 1-20, 7-10, 
13-54 
symbolic addresses 8-7 
SYSTEM command _ 5-24 to 5-25, 13-57 to 13-59 
PDM version 2-16 
system commands 5-24 to 5-26, 13-5 
ALIAS command 3-28, 5-21 to 5-23, 13-15 
PDM version 2-15 to 2-16 
CD command 3-21, 5-25, 7-11, 13-18 
CLS command 3-21, 5-5, 13-19 
DIR command 3-21, 5-25, 13-21 
DLOG command _ 5-6 to 5-8, 13-5, 13-23 
PDM version 2-10 
ECHO command _ 5-18, 13-5, 13-24 
PDM version 2-12 
from debugger command line 5-24 
IF/ELIF/ELSE/ENDIF commands 2-10 to 2-14, 
13-29 to 13-63 
IF/ELSE/ENDIF commands _ 5-18 to 5-19, 13-5, 
13-30 
conditions 5-21, 13-30 
predefined constants 5-19 
LOOP/BREAK/CONTINUE/ENDLOOP com- 
mands 2-11 to 2-12, 13-31 
LOOP/ENDLOOP commands _ 5-20 to 5-21, 
13-5, 13-32 
conditions 5-21, 13-32 
PAUSE command 2-13, 13-40 
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system commands (continued) 
QUIT command 1-20, 3-28, 13-45 
RESET command 3-4, 13-46 
SOUND command 13-54, D-2 
SYSTEM command 13-57 to 13-59 
PDM version 2-16 
system shell 5-25 
TAKE command 5-17, 6-10, 13-58 
PDM version 2-9 
UNALIAS command 5-23, 13-58 
PDM version 2-15 to 2-16 
USE command 7-11, 13-59 
system shells 5-24 to 5-25 
definition E-6 


—t debugger option 1-17, 1-20 
during debugger invocation 6-2, B-1 
with D_OPTIONS environment variable 
emulator 
DOS EMU 2-12 
OS/2 EMU 1-12 
simulator 
PC systems 1-7 
SPARC systems 3-5 
TAKE command 5-17, 6-10, 13-58 
executing log file 2-10, 5-6 
PDM version 2-9 
reading new memory map_ 6-10 
target cable connections EMU 1-7, 2-7 
target system EMU 1-2, 2-2 
connection to emulator EMU 1-8, 2-8, 3-1 to 
3-14 
definition E-6 
describing to the debugger C-1 to C-5; 
EMU 1-15 
board.cfg file EMU 1-3 
board.dat file EMU 1-3 
creating the board configuration file C-2 to 
C-5 
specifying the file C-5 
translating the file C-5; EMU 1-3 
memory definition for debugger 6-1 to 6-19 
resetting 3-4, 13-46 
TDM serial-port mode 6-12, 13-34 
TDXR register 6-13, 13-34 
terminating the debugger 1-20, 13-45 
test clock EMU3-8 
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text files 

displaying 3-14, 7-9 
TI320C5x device type C-3 
timing calculations EMU 3-10 to 3-12 
totem-pole output 

definition E-6 
traps taken 11-8 
TRCV register 6-13, 13-34 
TSPC control bit 13-34 
tutorial 

introductory 3-1 to 3-28 
type casting 3-24 to 3-25, 14-4 
type checking 3-20, 8-2 


UNALIAS command _ 5-23, 13-58 

PDM version 2-15 to 2-16 
UNIX 

using with the PDM_ 1-15 
unmarking areas 12-11 to 12-12 
UNSET command 2-5, 13-59 

deleting system variables 2-20 to 2-22 
USE command 7-11, 13-59 
utilities 

xev SIM 2-7 

xmodmap S/M 2-7 

xrdbp SIM 2-8 


-v debugger option 1-17, 1-20 
with D_-OPTIONS environment variable 
EVM 10; SIM 1-7, 3-5 
DOS EMU 2-12 
OS/2 EMU 1-12 
VAA command 12-22, 13-59 
VAC command 12-22, 13-60 
variables 
aggregate values in DISP window 3-21 to 3-23, 
4-16, 8-13 to 8-15, 13-22 to 13-25 
assigning to the result of an expression 2-19, 
13-13 
determining type 8-2 
displaying in different numeric format 3-24 to 
3-25, 14-5 
displaying/modifying 8-16 to 8-17 


variables (continued) 
PDM 2-18 to 2-20 
scalar values in WATCH window 4-17, 8-16 to 
8-17 
verifying 
installation EMU 1-16, 2-13; EVM12 
PC systems SIM 1-8 
SPARC systems SIM 2-6 
VGA 
definition E-6 
viewing profile data 12-17 to 12-21 
associated code 12-21 
data accuracy 12-19 
displaying areas 12-19 to 12-20 
displaying different data 12-17 to 12-18 
sorting data 12-19 
void expressions 14-4 
VR command 13-60 


WA command 3-17, 4-17, 5-11 to 5-12, 8-12, 8-16, 
13-61 to 13-62 
display formats 3-24 to 3-25, 8-21, 13-61 
menu selection 13-10 
watch commands 
menu selections 13-10 
pulldown menu 8-16 
WA command 3-17, 5-11 to 5-12, 8-12, 8-16, 
13-61 to 13-62 
WD command 3-19, 8-17, 13-62 
WR command _ 3-20, 8-17, 13-63 
WATCH window 3-17, 4-5, 4-17, 8-2, 8-16 to 8-17, 
13-61 to 13-62, 13-63 
adding items 8-16, 13-61 to 13-62 
closing 3-20, 4-29 to 4-30, 8-17, 13-63 
colors 10-6 
customizing 10-6 
definition E-6 
deleting items 8-17, 13-62 
editing values 8-4 
effects of LOAD command 8-17 
effects of SLOAD command 8-17 
labeling watched data 8-17, 13-61 to 13-62 
opening 8-16, 13-61 to 13-62 
WD command _ 3-19, 4-17, 8-17, 13-62 
menu selection 13-10 
WHATIS command 3-20, 8-2, 13-62 
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WIN command _ 3-5, 3-6, 4-20, 13-62 


window commands 13-4 
See also windows, commands 
WIN command 3-5 


windows 4-5 to 4-17 
active window 4-19 to 4-21 
border styles 10-8, 13-17 
CALLS window 3-11, 4-5, 4-9 to 4-10, 7-2, 7-9 
closing 4-29 
COMMAND window 4-5, 4-6, 5-2 
commands 
MOVE command _ 3-9, 4-24 
SIZE command 3-7, 4-22, 13-53 to 13-54 
WIN command _ 3-5, 3-6, 4-20, 13-38, 13-62 
ZOOM command _ 3-8, 4-24, 13-63 
CPU window 4-5, 4-15, 8-2, 8-12 
definition E-6 
DISASSEMBLY window _ 3-5, 4-5, 4-7, 7-2, 7-4 
DISP window 3-21 to 3-23, 4-5, 4-16, 8-2, 8-13 
to 8-15 
editing 4-28 
FILE window 3-14, 4-5, 4-8, 7-2, 7-4, 7-8 
MEMORY window _ 3-5, 4-5, 4-12 to 4-15, 8-2, 
8-6 to 8-11 
moving 3-9, 4-24 to 4-26, 13-38 
function keys 4-25, 13-69 
mouse method 4-24 
MOVE command 4-24 
XY positions 4-25, 13-38 
PROFILE window 4-5, 4-11 
resizing 3-7, 4-21 to 4-23 
function keys 4-23, 13-69 
mouse method 4-22 
SIZE command 4-22 
size limits 4-22 
while moving 4-25, 13-38 
scrolling 3-10, 4-26 to 4-27 
size limits 4-22 
View window, analysis interface 11-14 to 11-16 
WATCH window _ 3-17, 4-5, 4-17, 8-2, 8-16 to 
8-17 
zooming 3-8, 4-23 to 4-24 


WR command 3-20, 4-17, 8-17, 13-63 
menu selection 13-10 
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-x debugger option 1-17, 1-20; EVM10 
emulator 
DOS EMU 2-12 
OS/2 EMU 1-12 
simulator 
PC systems SIM 1-7 
SPARC systems 3-5 


X Window System 
changing the displayed font S/M 2-8 
colormapping S/M2-8 
displaying debugger on a different ma- 
chine 1-17, 1-18 
special keys S/M 2-7 
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X Window System (continued) 


using with the debugger S/M 2-7 to 3-8 


xev utility SIM 2-7 
xmodmap utility S/M 2-7 


.Xdefaults file, changing the displayed debugger 


font SIM 2-8 
xev utility SIM 2-7 
xmodmap utility S/M 2-7 


-z shell option 1-13 
ZOOM command _ 3-8, 4-24, 13-63 
zooming awindow 4-23 to 4-24 
mouse method 3-8, 4-23 
ZOOM command __ 3-8, 4-24, 13-63 
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